Self-hosted runner feature comparison
This page offers a comparison of the features available for CircleCI machine runner vs. CircleCI container runner.
Comparison matrix
| Feature | Description | Machine Runner | Container Runner |
|---|---|---|---|
Environment | Where jobs run and how resources are managed | Full VM/bare metal | Kubernetes Pods |
Configuration File | Primary file for runner setup | YAML config (location depends on OS) | Helm |
Resource Control | How compute resources are allocated | System level | Kubernetes limits |
Architecture Support | CPU architectures available for builds | AMD64/ARM64 with | |
Job Isolation | How jobs are kept separate | VM-level | Container-level |
Scaling | How runner capacity scales with demand | Kubernetes-based auto-scaling | |
Service Containers | Support for additional services in build | Not supported | Extensive support with resource controls |
Execution Modes | How runner handles job execution |
| Pod-based execution |
Docker Support | How Docker-in-Docker is handled | Native OS support | Possible with third-party tools |
Resource Cleanup | How build environments are cleaned after jobs | Working directory cleanup | Container lifecycle |
Feature Highlights
Machine Runner
-
Latest generation of machine-based runners.
-
Full access to underlying operating system.
-
Ideal for workflows requiring VM-level isolation.
-
Consistent environment variables with
CIRCLECI_RUNNER_*prefix. -
Supports SSH connectivity for debugging.
Container Runner
-
Kubernetes-native solution for container-based workflows.
-
Fine-grained resource allocation and constraints.
-
Supports service container configurations with pattern matching.
-
Advanced node selection via Kubernetes annotations.
-
Custom security contexts and volume mounting.
-
Support for spot instances via tolerations.
-
Configurable resource limits for primary and service containers.
-
Supports SSH connectivity for debugging - Open preview.
Key differences
Machine runner offers full VM isolation with the newest configuration patterns and improved controls.
Container runner leverages Kubernetes for:
-
Container-based isolation.
-
Better scaling capabilities.
-
Advanced resource management.
-
Multiple architecture support.
When to choose each runner
Machine runner: Choose for full system access, custom system dependencies, or when Kubernetes is not available.
Container runner: Best for cloud-native applications, teams using Kubernetes, and workloads that benefit from container orchestration.