CircleCI Runner FAQs

Last updated
Tags Cloud Server v3.x

What is the security model for the CircleCI runner?

When installing CircleCI 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 runner machine

This approach is the most secure; however, this means that if the job’s dependencies change, the 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.

No inbound connectivity is required by 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 and workspaces and artifacts work with CircleCI runner?

Caches, workspaces, and artifacts will be stored in the us-east-1 region of S3. If your runners are not in this region then you may see reduced performance. Although CircleCI is not currently charging for runner usage, you may be charged for data transfer and storage in the future.

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

What are the best practices for managing state between jobs?

The runner itself is unopinionated about this. Runner 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.

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.

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.