Start Building for Free

CircleCI Self-hosted Runner FAQs

1 week ago4 min read
Server v3.x

This page answers frequently asked questions for the CircleCI self-hosted runner product.

What is the security model for the CircleCI self-hosted runner?

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.

How do I install dependencies needed for my jobs?

There are two main approaches available for installing dependencies:

  • Allow the jobs to install their own 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).

  • Pre-install dependencies on the self-hosted runner machine

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

What connectivity is required?

In order to connect back to CircleCI to receive and execute jobs, outbound HTTPS connections to, are required.

How do caching, workspaces, and artifacts work with CircleCI self-hosted runners?

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.

What are the best practices for managing state between jobs?

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.

Can I run multiple agents on a single host?

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.

Can I delete self-hosted runner resource classes?

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

circleci runner resource-class delete <resource-class> --force

Who can create, delete, and view self-hosted runner resource classes?

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.

Can jobs on forks of my OSS project use my organization’s self-hosted runners if the fork is not a part of my organization?

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.

How long do inactive self-hosted runners persist in the self-hosted runner inventory page?

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.

How can I tell whether a host with a self-hosted runner installed is executing a job?

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

ps aux | pgrep -f circleci-launch-agent

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.

I installed my first self-hosted runner on macOS and the job is stuck in "Preparing Environment", but there are no errors, what should I do?

Try running the following two commands:

sudo chmod +x /var/opt/circleci/circleci-launch-agent
sudo /var/opt/circleci/circleci-launch-agent --config=/Library/Preferences/com.circleci.runner/launch-agent-config.yaml

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

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.