Install a CircleCI self-hosted runner (machine runner and container runner)
domain: circleci.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Create a namespace and resource class in the CircleCI web UI (Self-Hosted Runners section) or via the CLI: circleci runner resource-class create YOUR_NAMESPACE/YOUR_CLASS 'description' — copy the resource class token shown once at creation
For a machine runner on Linux/macOS, download the circleci-launch-agent binary, create /etc/circleci-launch-agent/launch-agent-config.yaml with the auth token and resource class, then install as a systemd service
For a container runner on Kubernetes, add the CircleCI Helm repository and install the chart: helm install container-agent container-agent/container-agent -n circleci --set agent.resourceClasses.YOUR_NAMESPACE/YOUR_CLASS.token=YOUR_TOKEN
Reference the resource class in a CircleCI config.yml job: machine: true with resource_class: YOUR_NAMESPACE/YOUR_CLASS (machine runner) or docker: [{image: ...}] with resource_class: YOUR_NAMESPACE/YOUR_CLASS (container runner)
Verify the runner appears as active in the CircleCI web UI under Self-Hosted Runners, then trigger a pipeline to confirm job dispatch
For the container runner, configure agent.maxRunningTasks in the Helm values to set the maximum concurrent jobs on the Kubernetes cluster
Known gotchas
The resource class token is shown only once at creation; store it in a secrets manager immediately — you cannot retrieve it later and must create a new resource class if lost
Machine runners run jobs in the same OS environment as the agent process; unlike GitHub Actions ephemeral runners, the environment persists between jobs unless you explicitly clean it up in a post-job step
Container runner requires the Kubernetes cluster to have outbound internet access to runner.circleci.com; configure egress rules before installation in restricted environments
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?