CircleCI Self-hosted Runner FAQs

When installing CircleCI self-hosted runner, you will be able to choose the user that executes jobs. It is up to you to ensure this user only has permissions you are comfortable letting jobs use.

There are two main approaches available for installing dependencies:

This approach is the most flexible, but will require providing the jobs sufficient privileges to install tools or install the tools in a non-overlapping manner (eg. into the working directory).

This approach is the most secure; however, this means that if the job’s dependencies change, the self-hosted runner machine must be reconfigured.

In order to connect back to CircleCI to receive and execute jobs, outbound HTTPS connections to runner.circleci.com, circleci-binary-releases.s3.amazonaws.com are required.

Caches, workspaces, and artifacts are methods you can implement to help persist data between jobs, and speed up builds. Caches, workspaces, and artifacts will be stored in the AWS us-east-1 region of S3. If your self-hosted runners are not in this region, then you may see reduced performance.

Find out more about these concepts below:

You can also find out more on the Persisting Data page.

If you would prefer to take complete control of artifact storage, CircleCI recommends you avoid the built-in steps and upload the artifacts directly to your chosen storage backend.

The self-hosted runner itself is unopinionated about this. Self-hosted runners can be configured to give each job a unique working directory and clean it up afterwards - but this is optional. And by default, nothing restricts the job from placing files outside of its working directory.

In general CircleCI recommends jobs rely on as little state as possible to improve their reproducibility. An effective way to accomplish this is to put cleanup steps at the start of a job so they are guaranteed to run regardless of what happened to a previous job.

Yes, by running multiple replicas of the launch-agent with unique names, it is possible to run as many agents (and therefore jobs) on a single host as you want. However, care must be taken to ensure that these jobs are sufficiently isolated from each other that they do not conflict if run at the same time.

Yes, self-hosted runner resource classes can be deleted through the CLI. Please be sure you want to permanently delete the resource class, as this action cannot be undone.

Before you can delete the resource class, any tokens associated with the resource class will need to be deleted first.

Once the tokens have been deleted, you can delete the resource class.

If you have lost your token, you can use the CLI to retrieve the token in order to delete it:

Organization admins in your VCS provider can create and delete self-hosted runner resource classes. Any organization user in your VCS provider that the resource class is associated with can view the resource class list through the CLI.

No, runner resource classes cannot be used by jobs that are not associated with the organization that owns the runner resource classes. Only forks of your OSS project that are a part of your organization may use the organization’s self-hosted runners.

If a self-hosted runner has not reported a "heartbeat" to CircleCI for three or more days, it will not show up in the inventory page on the CircleCI web app.

The recommended approach at this time is to query the host with the following command:

If the result of the command above returns greater than two processes, you can assume that the self-hosted runner is executing a task.

Note that you must check to see if there are greater than two processes because the grep process itself will count as one process and the launch agent process will count as a separate process.

Try running the following two commands:

Cancel the job and rerun it. If your job is still not running, file a support ticket.