Start Building for Free

Installing Self-Hosted Runners with the Web App

1 month ago2 min read
On This Page

This page describes how to install self-hosted runners through the CircleCI web app.


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

  • 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

Before you can make use of self-hosted runners, you will need to agree to the CircleCI Runner Terms. To be able to gain access to the Self-Hosted Runners section of the CircleCI web app, an admin in your organization needs to navigate to Organization Settings > Self-Hosted Runners, and agree to the terms.

Runner terms and conditions

Once the terms have been accepted, Self-Hosted Runners will appear permanently in the side navigation.

CircleCI mirrors VCS permissions for organizations. If you are an admin on your organization’s VCS, you are an admin on CircleCI. If you are unsure, check the admin permissions on your VCS.

CircleCI web app installation

In order to install self-hosted runners, you will need to create a namespace and resource class token. Please note that to create resource classes and tokens, you need to be an organization admin in the VCS provider. You can read about namespaces and resource classes on the Concepts page.

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

  1. On the CircleCI web app, navigate to Self-Hosted Runners.

    Runner set up
  2. If this is your organization’s first time using self-hosted runners, you’ll need to create a namespace as the first part of this step. Each organization can only create a single namespace. While not required, we suggest using a lowercase representation of your CircleCI account name. CircleCI will populate your org name as the suggested namespace by default in the UI.

  3. If your organization already use orbs, do not create a new namespace, enter the namespace your organization uses for orbs.

  4. The second input field is to create a name for your resource class for your organization’s self-hosted runners.

    Runner set up
  5. Copy and save the resource class token. Self-hosted runners use this token to claim work for the associated resource class.

    Runner set up
  6. You will need to follow the platform-specific installation instructions to continue. Click the tab in the UI that is relevant to your environment.

    Runner set up on your specific machine

    The post authentication platform-specific instructions are also documented on their own individual pages if you need to refer to them. See the Platform-specific instructions section for a list of these pages.

    Please note that if you would like to use self-hosted runners on Kubernetes, the instructions are not included in the UI, and you will need to refer to the Kubernetes page.

  7. You will be presented with configuration code for your new resource class. If you have an existing .circleci/config.yml file, add your new resource class below the existing jobs section, or add the whole jobs section if one doesn’t exist in your config. If you don’t have an existing .circleci/config.yml file, you can create the file and copy all of the code over.

    Runner set up

Platform-specific instructions

Listed below are the platform-specific installation pages.

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.