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 through the CircleCI web app. If you are interested in self-hosted runner on server, see the Self-hosted runners with the CLI page.

Container runner prerequisites

To install and run jobs, you will need to have root access, and have the following set up and installed:

  • Kubernetes 1.12+

  • Helm 3.x

  • A runner resource class token

  • A Kubernetes namespace without any other workloads

  • The checkout step configures Git to checkout over SSH - ensure that your cluster is configured to allow outbound connections over port 22 if you wish to use it

Machine runner prerequisites

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 install machine runners through the web app, 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. There is a Container tab for setting up container runner, as well as a Machine tab for setting up self-hosted runners in Linux, macOS, and Windows. Click the tab in the UI that is relevant to your environment.

    The instructions for specific platforms can be found in the web app, but also in our documentation. See the Platform-specific instructions section for a list of platform-specific pages.

  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.