Fast and easy self-hosted runner setup and real time tracking in the CircleCI UI

We recently revamped our freemium plan to be the most generous free CI/CD tier for developers on the planet. In addition to making powerful features and resources available on the Free plan, we’ve extended self-hosted runners to all CircleCI plans.

Making the Free plan feature rich wasn’t enough, so we’re striving to make our platform as friendly and intuitive as possible for developers of all skills and sizes. Today, we’re thrilled to introduce new simplified user experiences for self-hosted runners. We’ve added first-class support for self-hosted runners right in the UI. Whether you are code signing the next great mobile application for millions of users or testing new firmware on that Raspberry Pi in your basement, you can seamlessly take advantage of CircleCI’s self-hosted runners to get the job done.

You can now jump start installing and using a self-hosted runner in less than 5 minutes with a new installation experience through the UI. We’ll also help you keep track of all of your runner activity in a single view, so you can monitor and adjust your self-hosted runner pools to match the demands of your cloud pipelines, make informed scaling decisions, and identify and remediate stuck jobs or failed infrastructure.

Get started with self-hosted runners in 5 minutes or less

To get started, configure your first runner resource class quickly and easily in the CircleCI UI, all without having to download additional software. Resource classes are labels that enable you to isolate a group of self-hosted runners for a specific subset of jobs (ie. you might have one resource class for jobs that will run on macOS machines and a resource class for jobs that will run on Linux EC2 instances).

Creating a custom resource class

To create your first resource class, access the “Self-Hosted Runners” tab in the CircleCI UI to create your namespace (a unique identifier claimed by your organization) and resource class. After creating the namespace, follow the self-guided installation flow to install your first self-hosted runner.

Once you get a verification in the UI that a new self-hosted runner has been detected, you can use the example configuration file that’s shown in the UI or use an existing configuration file to run a job with your newly installed self-hosted runner.

See the docs for the latest list of supported operating systems, versions, and architectures.

Real-time tracking of your self-hosted runners

Following runner setup and installation, the CircleCI UI now tracks active runner agents and maintains a display of runner agents associated with your account. The display includes a real-time view of active and standby runners to help inform decisions on scaling and enable stuck jobs or failed infrastructure to be identified quickly and remedied easily.

Creating a custom resource class

Activate the Self-Hosted Runner UI for your CircleCI account

To enable self-hosted runners as part of your CircleCI cloud setup, an administrator in your CircleCI account should navigate to and then:

  1. Go to the Organization Settings page
  2. Click Self-Hosted Runners
  3. Accept the Runner Terms

You can learn more about building with self-hosted runners in the self-hosted runner course on CircleCI Academy.

What’s next?

Check out our community forum for instructions on how to get started with


If you have ideas about how to improve the runner experience, visit Canny to browse or submit new ideas. Head over to our community forum, Discuss, to let us know how you’re using runner. Visit the docs for more detailed information.