Get Started: Installing the CircleCI Runner

Last updated
Tags Cloud Server v3.x


The installation process assumes you have installed the following utilities 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.

  • curl (installed by default on macOS)

  • sha256sum (installed as part of coreutils on Linux apt/yum, macOS via brew)

  • systemd version 235+ (Linux only)

  • sepolicy (RHEL 8 only)

  • rpmbuild (RHEL 8 only)

  • permissions to create a user, and create directories under /opt.

Running jobs requires you have the following tools available on your machine:

  • tar

  • gzip

  • coreutils (Linux only)

  • git (recommended, but not required)


If you are installing runner 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 runner you will need to create a namespace and authentication token by performing the steps listed below – these commands can only be run by an owner/admin of your organization:

  1. Create a namespace for your organization’s runner resources.

    Each organization can only create a single namespace. If you already use orbs, this namespace will be the same namespace as the orbs use.

    Use the following command:

    circleci namespace create <name> <vcs-type> <org-name>

    For example, if your GitHub URL is, then use: circleci namespace create my-namespace github circleci.

  2. Create a resource class for your runner for your namespace using the following command:

    Your newly created namespace is required in the command to create your resource class.
    circleci runner resource-class create <name>/<resource-class> <description> --generate-token

    Example: circleci runner resource-class create my-namespace/my-resource-class my-description --generate-token.

    To create resource classes and tokens you need to be an organization administrator in the VCS provider.
    The default token cannot be retrieved again, so be sure to store it safely.


Download the launch agent binary and verify the checksum

The launch agent can be installed using the following script, which will use opt/circleci as the base install location.

First, set one of these variables as appropriate for for your installation target.

Installation Target Variable

For Linux x86_64


For Linux ARM64


For macOS x86_64


For macOS M1



export platform=darwin/amd64

Next, set the circleci-launch-agent version. Runners on cloud auto-update to the latest supported versions. For server, specific runner versions are validated for interoperability and runners do not auto-update. A table of server circleci-launch-agent versions can be found here.

For cloud, you can run the following:

export base_url=""

followed by:

export agent_version=$(curl "${base_url}/release.txt")

For server v3.1.0 and up, run the following, substituting <launch-agent-version> with the correct launch agent version for the version of server you are running (see Runner for server compatibility to find the correct version):

export agent_version="<launch-agent-version>"

Finally, run the following script to download, verify and install the binary.

# Set up runner directory
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"

Platform-specific instructions

Please refer to the platform-specific installation instructions:

For other platforms, see Available CircleCI runner platforms for more information.

Runner 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 runner, depending on your version of server:

Server version Launch Agent Version


Runner not supported







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.