CircleCI Self-hosted Runner FAQs
On This Page
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.
|Allowing jobs to access a docker daemon is equivalent to providing root access to the machine.|
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
circleci-binary-releases.s3.amazonaws.com are required.
|No inbound connectivity is required by a self-hosted runner. Any other required connectivity is dependent on the content of the jobs themselves.|
| Using the checkout step will require access to your VCS provider. Using the cache, workspace or artifact features will require outbound HTTPS connections to |
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.
|It may be possible to reduce build times by making use of caches that persist on the host between jobs, however this is a trade-off against reproducibility - and may also lead to disks filling up over time. As a result, this trade-off could lead to higher billable usage.|
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, 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.
circleci runner token delete <token-id>
Once the tokens have been deleted, you can delete the resource class.
circleci runner resource-class delete <resource-class>
If you have lost your token, you can use the CLI to retrieve the token in order to delete it:
circleci runner token list <resource_class>
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 /opt/circleci/circleci-launch-agent sudo /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.
- Suggest an edit to this page (please read the contributing guidefirst).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
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.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.