Start Building for Free

Container runner installation (Kubernetes)

4 months ago1 min read
Server v4.x
Server v3.x
On This Page

This page describes how to install CircleCI’s container runner.

Installation instructions

  1. Add the container runner Helm repo by running helm repo add container-agent

  2. Run helm repo update

  3. Run kubectl create namespace circleci to create the circleci Kubernetes namespace

  4. Create a file called values.yaml file containing the following:

          token: <resource_class_token>
  5. Run helm install container-agent container-agent/container-agent -n circleci -f values.yaml

Container runner configuration example

Once you have installed the container runner within your cluster, create and trigger a CircleCI job that uses the Docker executor to validate the installation. The fields you must set for a specific job to run using your self-hosted runners are:

  • image:

  • resource_class: <namespace>/<resource-class>

Simple example of how you could set up a job (cimg/base:2021.11 is a commonly used CirlceCI Docker image):

version: 2.1

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

      - build


Refer to the Troubleshoot Container Runner section of the Troubleshoot Self-hosted Runner guide if you encounter issues installing or running container runner.

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.