CircleCI self-hosted runners let a customer run jobs “on your own infrastructure” instead of on CircleCI’s hosted executors. The runner polls CircleCI for work, runs the job and returns status, logs and artifacts.[1] Runners are available on the Free, Performance and Scale plans and with CircleCI Server.[1][10] This article covers how runner use is limited and what usage-based charges apply to it and to the hosted plans.
Editions
CircleCI describes three installation options.[1]
| Option | What it is |
|---|---|
| Container runner | Installed in a Kubernetes cluster; the container-agent claims containerized jobs and runs each in an ephemeral pod. It can use CircleCI convenience images and custom Docker images[1] |
| Machine runner | Installed on a virtual or physical machine; each job runs in the environment where the runner binary is installed. Linux, Windows and macOS are supported[1] |
| Machine Runner Orchestrator | A Kubernetes controller that scales runner VMs with KubeVirt; the image and Helm chart are publicly available[1] |
Machine runner 3 replaces the launch-agent on cloud and on Server v4.4 and later.[2] The use rights for all of them rest on the Software as a Service Agreement, which defines Self-Hosted Applications as “optional hybrid applications” downloaded and installed on servers in the customer’s environment that “interact with our Services through an internet connection”, and on the Self-Hosted Applications Terms.[9][12] Those terms grant “a limited, non-exclusive, non-transferable, and non-sublicensable license” to download, install and access the applications on the customer’s Equipment, for the Term of the Order.[9]
Metrics
| Unit | Definition | Catalog row |
|---|---|---|
| Task | The smallest unit of work: a job with parallelism of one is one task, and a job with parallelism n greater than 1 creates n tasks[3] | Self-hosted runner task |
| Network egress | Data restored from CircleCI to self-hosted runners in caches and workspaces; the only network traffic that is billed[6] | Runner network egress |
| Storage | Gigabytes of retained artifacts, workspaces and caches, measured as size multiplied by retention period[6] | Storage |
| Docker layer caching run | Each job run with Docker layer caching enabled[8] | Docker layer caching job run |
| IP ranges data | Data used by jobs that opt in to IP ranges[7] | IP ranges data |
Counting / floors
Credits and runners. “You will need at least one credit on your account to use runners. Runner execution itself does not require credits, but one credit is required in case your jobs use storage or networking.”[1] The pricing FAQ confirms that “CircleCI does not charge per build minute on self-hosted runners”.[4] A customer therefore pays for platform access (plan, active users) and for the data it moves, not for runner minutes. See Runners need at least one credit but are not billed per minute.
Concurrency. Self-hosted runners “are limited by the total number of self-hosted runner jobs (tasks) across your organization”.[2] The pricing page lists 5 concurrent tasks on Free, 20 on Performance and unlimited on Scale.[4] The limit is shared: “An organization’s runner concurrency limit is shared with any existing machine self-hosted runners”, and container runner by default schedules at most 20 tasks at once, a Helm value that can be raised if the plan allows.[3] The plans overview lists “Additional self-hosted runners” for Performance and “Unlimited self-hosted runners” for Scale.[10] See Runner concurrency is shared across machine and container runners and A job with parallelism n creates n runner tasks.
Namespaces and resource classes. A runner needs a namespace and a resource class. Each organization “can claim one unique and immutable namespace”, the same one used for orbs, and a resource class such as namespace/name labels a pool of runners. Creating a resource class generates a token that “only has access to claim tasks”.[2][3] Organization admins in the version control provider can create and delete resource classes.[3]
Network egress. CircleCI says that “the only network traffic that will result in billing is accrued through restoring caches and workspaces to self-hosted runners”.[6] Egress triggered by cloud executors “is not passed on to the customer”.[4] The allowance is 1 GB on Free, 5 GB on Performance and 50 GB on Scale; overage is 420 credits per GB, which the documentation prices at USD 0.252 per GB.[4][5]
Storage. Storage is billed when artifacts, workspaces and caches are retained beyond the plan allowance of 2 GB, 2 GB and 200 GB. CircleCI “multiplies the object’s size by its configured retention period to get its total GB-days”, and this is added once, to the billing period in which the object was saved.[4][6] The default and maximum retention is 15 days for workspaces and caches and 30 days for artifacts. Paid plans can shorten the periods under Plan, Usage Controls, and a job can set cache retention between 1 and 15 days in configuration.[6] Changes apply to newly created objects only.[6] See Custom storage retention and the rules on storage calculation and default retention.
Docker layer caching. DLC “is available on all CircleCI plans” and “costs 200 credits per job run”, charged in addition to compute. A workflow with three parallel Docker build jobs consumes 600 credits each time it runs.[4][8] Docker layer caching is among the features not supported on self-hosted runners.[1]
IP ranges. The feature is available on Performance and Scale and “consumes 450 credits from your account for each 1 GB of data” used by jobs with IP ranges enabled. The data pulled to start the container before the job executes is not counted.[7]
Virtualization & partitioning
Runners are not licensed per host, core or virtual machine. The runner platform is the customer’s own, and the limit is on concurrent tasks. A customer can install many runner machines and still be capped by the organization’s task limit. Where a runner runs inside Docker or Kubernetes, the container runner pods and the Machine Runner Orchestrator virtual machines are the customer’s compute, but they are not counted as licensed units either.[1] The article virtualization and partitioning sets out the general principles for such metrics.
Cloud / BYOL
Runner compute is bring-your-own by design, and the customer carries its infrastructure cost. Outbound HTTPS connections to runner.circleci.com and CircleCI’s binary release bucket are needed, with no inbound connectivity.[3] CircleCI treats security as a shared responsibility: machine runners “let you choose the user that executes jobs”, and “allowing jobs to access a Docker daemon is equivalent to providing root access to the machine”.[3] Platforms with Supported status receive documentation and support “within the usual Advanced Service Level Agreements (SLAs)”: Ubuntu 18.04 or later on x86_64 and ARM64 for both runner types, Kubernetes for container runner, and macOS 11.2 or later, Windows Server 2019 or later and several Linux distributions for machine runner.[1] The rule row is Supported runner platforms receive support within Advanced SLAs.
Programs
- Public repositories. Self-hosted runners “are Not Available” for public projects that have the Build forked pull requests setting enabled, for security reasons. Only forks that belong to the organization can use its runners.[2][3] See Self-hosted runners are not available for forked pull request builds on public projects.
- Custom storage retention. Shortening retention lowers the monthly bill.[6]
- Update obligation. CircleCI may release updates to Self-Hosted Applications, and the customer agrees to install them promptly; older versions “may not properly operate until you comply”.[9] See Self-Hosted Application updates must be installed promptly.
Audits and compliance
The agreements retrieved do not give CircleCI an audit right over runner machines. Compliance is exercised through the Plan Usage pages, which break network and storage usage down by project and by object type (cache, artifact, workspace).[6] Points to check include the number of runner tasks in use against the plan limit, cache and workspace restores to runners that generate egress, retention settings left at defaults, and jobs that opt in to IP ranges or DLC. The customer warrants that it owns or licenses the Equipment on which Self-Hosted Applications are installed and is “solely responsible for the configuration, security, maintenance, and costs of such Equipment”.[9]
Out of scope
- Hardware, operating system and Kubernetes licences on the machines that host runners, which are the customer’s own.
- Scale-plan negotiated runner limits, which are not public.
- Support package prices for runner issues, which CircleCI does not publish.