Container runner, a new container-friendly self-hosted runner, is now available for all CircleCI users. Self-hosted runners are a popular solution for customers with unique compute or security requirements. Container runner reduces the barrier to entry for using self-hosted runners within a containerized environment and makes it easier for central DevOps teams to manage running containerized CI/CD jobs behind a firewall at scale.

Running containerized jobs

CircleCI’s Docker executor allows you to take full advantage of the speed and flexibility benefits of containerization in your continuous integration workflows. Running jobs in containers is a fast and convenient way to ensure your builds have access to all required libraries and dependencies without the additional spin-up time required to launch a full machine environment.

Container runner eliminates enables users to use the Docker syntax in their config.yml file. This means that users are free to use their own custom images or CircleCI convenience images and can easily execute secondary containers during job execution.

Automatically scaling infrastructure

For most development teams, infrastructure needs fluctuate throughout the day, and maintaining a fixed level of compute resources to accommodate peak workloads can quickly result in runaway cloud costs. To address this challenge, it is helpful to have a solution that can dynamically scale your infrastructure up and down in response to demand.

Container runner integrates with Kubernetes for fast, effortless container orchestration. That means users have just one runner agent to manage, and the container runner will spin up ephemeral pods as needed to execute concurrent CI jobs. Whether you need to run 5 jobs or 100 jobs at the same time, a single instance of container runner is all you need to ensure you have sufficient infrastructure in place.

Installing container runner in your Kubernetes cluster

Installing your first container runner requires just a few steps, and can be done easily through the CircleCI UI. Simply create a CircleCI namespace (if one does not already exist for your organization) and runner resource class in the CircleCI web app, install the container runner in your Kubernetes cluster using Helm, and add a new job to your CircleCI config.yml file which uses the Docker executor and your container runner’s resource class.

Below is an example configuration that uses the container runner for the build job:

version: 2.1

      - image: cimg/base:2021.11
    resource_class: <namespace>/<resource-class>
      - checkout
      - run: echo "Hi I'm on Runners!"

      - build

For more information on installing container runner and triggering runner jobs from CircleCI, visit the container runner installation docs.


Running CI/CD jobs in a containerized environment behind a firewall is an important part of many software teams’ day-to-day development work. At CircleCI, we believe it’s important to support teams no matter where they build their software. Whether you are building in the cloud or in your own infrastructure, CircleCI meets you where you are.

If you have ideas about how to improve the runner experience, visit Canny to browse or submit new ideas. Go to our community forum, Discuss, to let us know how you’re using runner.

The original self-hosted runner, machine runner, is primarily used for virtual and physical environments. Container runner is a complement to the machine runner, not a replacement. For information on machine runner, visit the docs.