Docs
circleci.com
Start Building for Free

Installing Self-Hosted Runners with the CLI

2 days ago3 min read
Cloud
Server v3.x
On This Page

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

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

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.

  1. 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>
  2. 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.

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.

  1. 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"
  2. 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 TargetVariable

    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 versionLaunch 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.

  3. Continue with the platform-specific instructions in the next section.

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 versionLaunch 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


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.

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.