Installing Self-Hosted Runners with the CLI

1 week ago • 4 min read

Cloud Server v3.x

This page describes how to install self-hosted runners through the CLI.

Installing self-hosted runners is now available directly in the CircleCI web app! You will need to agree to the Runner Terms before this option is available to you in the UI.

Prerequisites
Self-hosted runner Terms Agreement
Command line installation
- Continued for Linux, macOS, and Server
- Platform-specific instructions
Referencing your self-hosted runner on a job
Self-hosted runners for server compatibility
Additional Resources

Prerequisites

To install and run jobs, you will need to have root access, and have the following utilities and tools installed on your system:

CircleCI CLI. If you are installing runner for server, the CircleCI CLI needs to be configured using a server API key. Run circleci setup to configure the CLI and access the option to supply a new API token if required.
coreutils (Linux only)
curl (installed by default on macOS)
sha256sum (if not pre-installed):
- brew install coreutils for macOS (requires Homebrew)
- sudo apt install coreutils for Ubuntu/Debain
- sudo yum install coreutils for Red Hat
tar
gzip
sepolicy (RHEL 8 only)
rpmbuild (RHEL 8 only)

Self-hosted runner Terms Agreement

If you are installing and using self-hosted runners through the CLI, you are agreeing to the CircleCI Runner Terms.

Command line installation

If you are installing self-hosted runners for server, the CircleCI CLI needs to be configured using your server API key. Run circleci setup to configure the CLI and access the option to supply a new API token if required.

In order to install self-hosted runners, you will need to create a namespace and authentication token by performing the steps listed below. Please note that to create resource classes and tokens you need to be an organization administrator in the VCS provider.

You can view your runners on the inventory page, by clicking Self-Hosted Runners on the left navigation.

Create a namespace for your organization’s self-hosted runners. Please note, CircleCI will autogenerate a namespace based on your organization’s name. Verify this is the namespace you want to use. Each organization can only create a single namespace. We suggest using a lowercase representation of your CircleCI organization’s account name. If you already use orbs, this namespace should be the same namespace orbs use.

If you receive an error creating a namespace, check to see if you have an existing one, and move on to step 2 below, using your existing namespace.

It is recommended to use the following command to create a namespace:
```
circleci namespace create <name> --org-id <your-organization-id>
```
Create a resource class for your self-hosted runner’s namespace using the following command:
```
circleci runner resource-class create <namespace>/<resource-class> <description> --generate-token
```
Your namespace is required in the command to create your resource class. Example: circleci runner resource-class create my-namespace/my-resource-class my-description --generate-token.

The token cannot be retrieved again, so be sure to store it safely.

If you are using Linux, macOS, or Server, continue with the directions below. Otherwise, skip to the Platform-specific installation instructions.

Continued for Linux, macOS, and Server

Be sure to complete the steps in the Command line installation section before moving on to the steps below.

Save the script below as download-launch-agent.sh in the root of your project. When run (see the next step) the script will download the launch agent binary, verify the checksum, and set the circleci-launch-agent version.

Self-hosted runners on cloud auto-update to the latest supported versions. For server, specific self-hosted runner versions are validated for interoperability, and self-hosted runners do not auto-update.

#!/usr/bin/env sh

set -eu pipefail

echo "Installing CircleCI Runner for ${platform}"

base_url="https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent"
if [ -z ${agent_version+x} ]; then
  agent_version=$(curl "${base_url}/release.txt")
fi

# Set up runner directory
echo "Setting up CircleCI Runner directory"
prefix=/opt/circleci
sudo mkdir -p "${prefix}/workdir"

# Downloading launch agent
echo "Using CircleCI Launch Agent version ${agent_version}"
echo "Downloading and verifying CircleCI Launch Agent Binary"
curl -sSL "${base_url}/${agent_version}/checksums.txt" -o checksums.txt
file="$(grep -F "${platform}" checksums.txt | cut -d ' ' -f 2 | sed 's/^.//')"
mkdir -p "${platform}"
echo "Downloading CircleCI Launch Agent: ${file}"
curl --compressed -L "${base_url}/${agent_version}/${file}" -o "${file}"

# Verifying download
echo "Verifying CircleCI Launch Agent download"
grep "${file}" checksums.txt | sha256sum --check && chmod +x "${file}"
sudo cp "${file}" "${prefix}/circleci-launch-agent" || echo "Invalid checksum for CircleCI Launch Agent, please try download again"

Set your platform and run the download-launch-agent.sh script to download, verify, and install the binary. If you are using cloud, use the table below to find your platform variable:

Installation Target Variable

For Linux x86_64

platform=linux/amd64

For Linux ARM64

platform=linux/arm64

For macOS x86_64

platform=darwin/amd64

For macOS M1

platform=darwin/arm64

For example, on cloud, to set your platform for macOS M1 and run the download-launch-agent.sh script, run the following:
```
export platform=darwin/arm64 && sh ./download-launch-agent.sh
```
For server v3.1.0 and up, use the table below to find the compatible launch agent version for the version of server you are running:

Server version Launch Agent Version

3.0

Runner not supported

3.1

1.0.11147-881b608

3.2

1.0.19813-e9e1cd9

3.3

1.0.29477-605777e

3.4

1.0.33818-051c2fc

Substitute <launch-agent-version> with your launch agent version for server and run the following:
```
export agent_version="<launch-agent-version>" && sh ./download-launch-agent.sh
```
Note: Once your runner is successfully set up, you can delete the download-launch-agent.sh file.
Continue with the platform-specific instructions in the next section.

Installation Target	Variable
For Linux x86_64	`platform=linux/amd64`
For Linux ARM64	`platform=linux/arm64`
For macOS x86_64	`platform=darwin/amd64`
For macOS M1	`platform=darwin/arm64`

Platform-specific instructions

Please continue with the platform-specific installation instructions below. This should be done only after you have created your namespace and resource class, and run the download-launch-agent.sh script from the previous section.

For other platforms, see the Available CircleCI self-hosted runner platforms page for more information.

Referencing your self-hosted runner on a job

After setting up your self-hosted runner, you will need to reference it on a job by setting some fields in your .circleci/config.yml file. The fields you must set for a specific job to run using your self-hosted runners are:

machine: true
resource_class: your-namespace/your-resource

Here is a simple example of how you could set up a job:

version: 2.1
workflows:
  testing:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: your-namespace/your-resource
    steps:
      - run: echo "Hi I'm on Runners!"

The job will then execute using your self-hosted runner when you push the config to your VCS provider.

Self-hosted runners for server compatibility

CircleCI runner is available from server v3.1.0

Each minor version of server is compatible with a specific version of circleci-launch-agent. The table below lists which version of circleci-launch-agent to use when installing self-hosted runners, depending on your version of server.

Server version	Launch Agent Version
3.0	Runner not supported
3.1	1.0.11147-881b608
3.2	1.0.19813-e9e1cd9
3.3	1.0.29477-605777e
3.4	1.0.33818-051c2fc

Additional Resources

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Suggest an edit to this page (please read the contributing guide first).
To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.