CircleCI’s Machine Runner Orchestrator turns a KubeVirt-backed Kubernetes cluster into an elastic self-hosted runner fleet. The controller polls CircleCI for queued work, adjusts a KubeVirt VirtualMachinePool, and starts or retires runner VMs for each configured resource class. To deploy it, you need Kubernetes with KubeVirt already installed, a CircleCI runner namespace and resource-class token, and a Helm installation whose scaling limits match the capacity of your cluster. The orchestrator chart does not install Kubernetes or KubeVirt.
This guide covers the complete path: infrastructure checks, CircleCI identity, Helm values, job configuration, scaling, security, upgrades, and troubleshooting. The examples use the current chart release documented by CircleCI, version 1.0.0.
As an Amazon Associate I earn from qualifying purchases.
What the orchestrator does
The orchestrator is a Kubernetes controller for self-hosted CircleCI machine runners. Each configured CircleCI resource class maps to a KubeVirt virtual-machine pool. The controller checks CircleCI demand, calculates a desired replica count, and updates that pool. A VM boots with the runner software and claims work for its resource class; after the job and any configured idle period, it can shut itself down so the pool contracts.
The controller polls CircleCI approximately every five seconds. Its demand calculation considers unclaimed tasks and running tasks for the class, adds configured headroom when work exists, clamps the result between minReplicas and maxReplicas, and applies maxSurge when launch requests need to be limited. Scale-in is cooperative: the pool does not forcibly stop a busy VM. A VM finishes its task and then exits, or exits after its idleTimeout; without an idle timeout, an idle VM can wait indefinitely.
#1 Best Overall
- [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
- [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
- [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
- [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
- [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.
CircleCI’s 1.0.0 release added one deployment serving multiple classes, including CPU, GPU and ARM workloads, and support for GKE, AKS, EKS and other KubeVirt-based Kubernetes clusters. The release note says the orchestrator is included with self-hosted runners on every CircleCI plan at no additional charge. Verify those statements against the current release documentation before applying them to a later chart version: CircleCI’s 1.0.0 release note.
A useful mental model is “CircleCI demand outside, KubeVirt capacity inside.” CircleCI still schedules the job and enforces the organization’s concurrency limits; Kubernetes and KubeVirt provide the VM capacity; the orchestrator synchronizes the two.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Check infrastructure before installing
Kubernetes and KubeVirt are mandatory
Provision a Kubernetes cluster and install KubeVirt before installing the orchestrator chart. The chart does not install KubeVirt, create a virtualization-capable node pool, or solve storage and networking for you. Check the version compatibility matrix linked from the Machine runner orchestrator guide; that guide documents testing with KubeVirt v1.8.
Size the cluster for the largest pool you permit, not only for its current average. The sum of the classes’ possible VM replicas, Kubernetes system workloads, KubeVirt components, and any surge capacity must fit the node pools. If a pool can grow to 20 VMs, the cluster needs resources for those 20 VMs plus overhead even if your normal load is two jobs.
Confirm nested virtualization
Many deployments run KubeVirt inside a cloud VM, which requires nested virtualization. Confirm support with your cloud provider and node-pool configuration before creating the runner pool. CircleCI’s GKE example calls for an n2, n2d, c2, or c2d machine type and says that e2 does not support nested virtualization. Those machine families are GKE-specific guidance, not a universal hardware requirement; other providers have different instance names and constraints.
Know the default VM and override it deliberately
The documented default runner VM uses Ubuntu 24.04, 2 GiB of memory and one CPU. Its CircleCI-maintained container disk includes Docker and common CI tools. That baseline is suitable for lightweight builds, but compilation, browser testing, large Docker images, GPU jobs, ARM workloads or large dependency caches usually need different resources. Use a class-specific KubeVirt spec, or put shared values in resourceClassDefaults, for CPU, memory, disks, images and related VM settings. VM capacity and disk performance remain your responsibility.
| Requirement | What to verify | Why it matters |
|---|---|---|
| Kubernetes | Cluster is available to your Helm client and has enough allocatable CPU, memory and storage. | The controller and every runner VM consume cluster resources. |
| KubeVirt | Installed at a version compatible with the orchestrator; the guide documents tests with v1.8. | The chart creates and scales KubeVirt virtual-machine pools. |
| Virtualization | Nested virtualization is enabled where Kubernetes nodes themselves are virtual machines. | Without it, VMs may fail to start or run without hardware acceleration. |
| Network egress | Controller and VMs can reach the applicable CircleCI API endpoint and required registries. | They must poll for work, register runners and download build dependencies. |
| Capacity headroom | Maximum replicas plus surge and Kubernetes overhead fit the node pools. | Demand spikes otherwise leave tasks queued or pods unschedulable. |
Create the CircleCI runner identity
Choose the organization namespace
In CircleCI, an organization administrator creates or selects the namespace used by self-hosted runners. An organization generally has one namespace; an existing namespace may already be present because the organization uses orbs. Namespace names accept lowercase letters, numbers, underscores and dashes. Keep the namespace distinct from the Kubernetes namespace you will create later: they are separate identifiers.
Create a resource class and save its token
Open the organization’s Runners interface and create a custom resource class, or use the CircleCI CLI:
Rank #2
- 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
- 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
- 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
- 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
- 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.
circleci runner resource-class create acme/build "Linux build runners" --generate-tokenReplace acme/build with your own namespace/name. Resource-class names additionally permit uppercase letters, colons and plus signs, although simple lowercase names reduce quoting and typing errors. The generated token is displayed only once according to CircleCI’s guide. Copy it immediately into your approved secret-management system; do not commit it to a values file, repository or job configuration.
The resource class is the scheduling key. A job that requests acme/build can only be claimed by runners registered for exactly that class. Decide whether you need one general class or separate classes such as acme/small, acme/large, acme/gpu or acme/arm before writing Helm values.
Recommended Free Tools
Prepare and install the Helm chart
Create a Kubernetes namespace
Use a dedicated Kubernetes namespace so that the controller, its service account, secrets and KubeVirt resources are easy to audit:
kubectl create namespace circleci-runnersIf the namespace already exists, keep using it. The CircleCI namespace and this Kubernetes namespace do not have to share a name.
Write values for a resource class
The current guide documents chart version 1.0.0 and the repository https://packagecloud.io/circleci/machine-runner-orchestrator/helm. A minimal values structure places each class under provisioner.resourceClasses. Render the token from your secret manager when you generate the file rather than storing a literal credential in source control:
provisioner:
resourceClasses:
acme/build:
token: "${CIRCLECI_RUNNER_TOKEN}"
scaling:
minReplicas: 1
maxReplicas: 10
headroom: 1
maxSurge: 2
scaleDownDelay: 300s
idleTimeout: 600sThe exact supported fields include the runner token, optional cloud-init userData, scaling settings, runner execution settings, extra disk mounts and the KubeVirt VM spec. Use resourceClassDefaults for common settings and override them inside an individual class when one pool needs different CPU, memory, image or disks. The chart also supports pre-existing Kubernetes Secrets and ConfigMaps; use those integrations when your cluster’s secret-management policy requires them.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchThe example values are an illustration of relationships, not a universal capacity recommendation. Choose replica limits from measured job concurrency, VM startup time, node capacity and your CircleCI plan’s concurrency allowance. CircleCI’s scaling guidance warns against starting compute that the plan cannot use.
Add the repository and install a pinned version
-
Add the repository:
helm repo add machine-runner-orchestrator https://packagecloud.io/circleci/machine-runner-orchestrator/helm helm repo update -
Install chart version 1.0.0 into the namespace:
helm upgrade --install circleci-machine-runner machine-runner-orchestrator/machine-runner-orchestrator --version 1.0.0 --namespace circleci-runners --create-namespace --values values.yamlPinning prevents an unplanned chart change. Review the chart changelog and compatibility notes before changing the version because CircleCI warns that configuration names and defaults can change while the product evolves.
Rank #3
New Bee Guitar Cable 10ft Electric Instrument Bass AMP Cord- [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
- [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
- [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
- [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
- [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by
-
Inspect the controller and generated resources:
kubectl -n circleci-runners get deploy,pods kubectl -n circleci-runners get virtualmachinepool kubectl -n circleci-runners logs deploy/circleci-machine-runnerThe deployment name can differ if you choose a different Helm release name. Use
kubectl get deploy -n circleci-runnerswhen in doubt.
Configure CircleCI Server when applicable
For CircleCI Cloud, use the default API endpoint. For a self-hosted CircleCI Server installation, set provisioner.circleciAPIAddr to the Server instance URL. The guide says this value is injected into every VM and that registration fails if it is omitted. Ensure both the controller and each VM can resolve and reach that URL through firewalls, proxies and network policies. The Server example also uses a CircleCI API token in addition to the resource-class token; keep both in Kubernetes secret storage and grant only the permissions required by the deployment.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Understand and tune scaling
Scaling is a capacity and security decision, not just a cost setting. The values below determine how quickly new VMs appear, how much warm capacity is retained and how long idle machines remain available.
| Setting | Behavior | Operational choice |
|---|---|---|
minReplicas |
Warm floor for the pool. A value of 0 permits scale-to-zero. |
Use a positive floor for latency-sensitive builds; use zero when startup delay is acceptable. |
maxReplicas |
Hard upper bound on pool size. | Keep it within schedulable cluster capacity and plan concurrency. |
headroom |
Extra warm VMs above current task demand while tasks exist. | Reduces queue time at the cost of idle capacity. |
maxSurge |
Limits launch requests above VMs already ready. | Use it to ramp in waves instead of overwhelming nodes, storage or image registries. |
scaleDownDelay |
Waits after demand falls before reducing the desired pool size. | Absorbs short gaps between jobs and prevents rapid scale oscillation. |
idleTimeout |
Allows an idle VM to shut itself down after the configured period. | Set it to bound idle resource use; without it, idle VMs wait indefinitely. |
Choose a warm pool or scale-to-zero
A positive minReplicas and modest headroom provide faster first-job starts because VMs are already booted. Scale-to-zero minimizes idle consumption but adds Kubernetes scheduling, VM boot and runner-registration time to the first job. Measure your organization’s acceptable queue time rather than assuming one policy fits every class.
Use surge and delay together
maxSurge controls the size of each launch wave; scaleDownDelay controls how long the pool waits before shrinking. A low surge protects a small cluster but can lengthen a large burst. A very short delay can repeatedly terminate and recreate capacity when jobs arrive in waves. Tune both against observed VM startup and job-arrival patterns.
Separate classes when workloads differ
A single deployment can serve multiple classes. Put shared settings in resourceClassDefaults, then define class-specific KubeVirt specifications for CPU-heavy, GPU, ARM or memory-heavy jobs. CircleCI’s 1.0.0 release specifically added multi-class support for these workload types. Separate classes also make authorization and capacity accounting clearer: a GPU queue cannot consume every small-build VM, and an ARM job cannot accidentally land on an x86 pool.
Free tools Windows power users keep installed
One-click scans. No signup required.
Account for CircleCI concurrency
The scaler can request replicas for queued demand, but CircleCI plan concurrency may limit how many jobs can run simultaneously. Set maxReplicas near the usable concurrency and cluster capacity rather than the theoretical queue size. Otherwise Kubernetes may create VMs that remain unable to claim work.
Target the fleet from CircleCI jobs
Jobs must explicitly request the configured resource class. A minimal configuration is:
Rank #4
- Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
- Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
- All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
- Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
- Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
version: 2.1
jobs:
build:
machine: true
resource_class: acme/build
steps:
- checkout
- run: echo "Hi from a self-hosted runner"Use the exact namespace/name key from Helm values. Set machine: true; do not add CircleCI-hosted machine.image aliases to a self-hosted machine job. A typo, a different namespace or a class that is absent from the deployment leaves the task unclaimed while the orchestrator watches the configured classes.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →For distinct pools, assign jobs explicitly, for example acme/gpu for GPU tests or acme/arm for architecture-specific builds. Keep class names and their intended hardware documented in the repository so a future change does not silently route a workload to the wrong VM type.
Secure the controller, VMs and jobs
Keep the resource-class token out of the guest
The chart’s default sidecar proxy attaches the resource-class token only when the controller claims work. This keeps the class credential out of the guest VM. Disabling the sidecar passes the token to the VM and removes support for grantSudo and SSH, according to the orchestrator guide. Leave the sidecar enabled unless you have a documented reason and compensating controls.
Store class tokens, CircleCI Server API tokens and cloud-init data in Kubernetes Secrets or an external secret manager. Restrict RBAC so only the controller and authorized operators can read them. Avoid putting credentials in ordinary ConfigMaps, Helm history, job logs or pull requests.
Treat Docker access as root-equivalent
CircleCI’s self-hosted runner FAQ states: “Allowing jobs to access a Docker daemon is equivalent to providing root access to the machine.” Machine runners let the operator choose the job-execution user, but the operator is responsible for limiting that user’s permissions. Pre-installing trusted dependencies on the VM is described as the more secure option; the trade-off is that dependency changes require rebuilding or reconfiguring the machine image.
Isolate untrusted code
Persistent self-hosted machines can retain files, credentials or processes between tasks if cleanup is incomplete. CircleCI warns about malicious programs, sandbox escape, network exposure and unwanted persistent data. Use trusted-job policies, least-privilege users, restrictive network policies, disposable VMs where practical, controlled caches and explicit cleanup. Do not place production credentials or unrestricted internal network access on a runner intended for untrusted contributions.
CircleCI’s runner concepts documentation says self-hosted runners are unavailable for public projects when the “Build forked pull requests” setting is enabled, for security reasons. Check that project setting before diagnosing a public-project job that never reaches your fleet: self-hosted runner concepts.
Operate and troubleshoot the fleet
Verify demand, provisioning and registration in order
-
Confirm the job’s
resource_classexactly matches a key underprovisioner.resourceClasses. -
Check the provisioner logs for task counts, desired replicas and errors:
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.kubectl -n circleci-runners logs deploy/circleci-machine-runner --follow -
Inspect the KubeVirt pool and VM objects:
kubectl -n circleci-runners get virtualmachinepool,virtualmachine,pods -
After a VM starts, inspect the runner service and cloud-init logs inside that VM. Registration failures commonly indicate an invalid class token, an unreachable Server API address or cloud-init that did not run.
-
Check node events and storage when VMs remain pending. Unschedulable CPU, memory, disks, missing virtualization support or network policy blocks are cluster-level causes rather than CircleCI scheduling errors.
Know which changes apply immediately
Scaling configuration and class credentials hot-reload. KubeVirt VM spec values and userData apply at boot, so existing VMs do not automatically receive those changes. After validating the new values, recycle existing VMs in an orderly manner so active jobs finish and new machines boot with the updated specification. Plan the recycle around your queue and concurrency limits.
Interpret common symptoms
| Symptom | Likely causes | Checks |
|---|---|---|
| Job remains queued | Class-name mismatch, invalid token, no replicas allowed, or plan concurrency exhausted. | Compare the job target with Helm keys; read provisioner task counts; check CircleCI concurrency. |
| Pool never creates VMs | Cluster lacks capacity, KubeVirt is unhealthy, or nested virtualization is unavailable. | Inspect VirtualMachinePool events, node conditions and KubeVirt components. |
| VM boots but does not register | Wrong token, missing Server API address, blocked egress or failed cloud-init. | Review VM runner-service/cloud-init logs and test API reachability from the guest. |
| Idle VMs never disappear | idleTimeout is unset or scale-down delay has not elapsed. |
Check effective Helm values and the VM’s idle state; a busy VM is not force-stopped. |
| New sizing is absent | Only a hot-reloadable field was changed, or existing VMs have not been recycled. | Distinguish scaling/token changes from boot-time spec and userData changes. |
Choose an orchestration design deliberately
CircleCI Cloud or CircleCI Server
Cloud deployments use the standard CircleCI endpoint. Server deployments set provisioner.circleciAPIAddr, inject that address into VMs and provide the additional Server API credential shown in the guide. Server networks need explicit DNS, routing, firewall and proxy validation because a VM that cannot reach the configured endpoint cannot register even when KubeVirt is healthy.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesOne class or several
One class is easiest to operate when every job needs the same VM shape. Multiple classes add configuration and capacity accounting but prevent incompatible workloads from sharing a pool and allow independent scaling bounds. Use separate classes when CPU, GPU, architecture, disk or trust requirements differ.
Continuous agents or single-task machines
CircleCI’s general self-hosted scaling documentation describes two execution patterns. In continuous mode, an agent polls for further work after completing a task; in single-task mode, an ephemeral machine handles one task and then exits. The orchestrator’s idle timeout and scale-in behavior are particularly relevant to continuous agents, while single-task designs provide stronger cleanup boundaries at the cost of more frequent VM startup. Choose based on isolation requirements, boot latency and cache strategy: CircleCI’s self-hosted runner scaling guide.
Plan upgrades and release changes
Pin the chart version and read the release notes before upgrading. CircleCI’s 1.0.0 note says the product was renamed from runner-provisioner; existing deployments must be uninstalled and reinstalled under the new chart name, with runners offline during the transition. Schedule that maintenance window so no active job is interrupted, drain or stop new work first, and retain a tested copy of your values and secret references.
The same release note says version 1.0.0 patches two high-severity gRPC-Go denial-of-service vulnerabilities, CVE-2026-84304 and CVE-2026-84445. Confirm the release note and current security advisories when deciding whether those identifiers apply to your installed chart or a later version. Do not infer that a chart upgrade alone updates every guest operating-system package; maintain the VM image and dependencies separately.
Quick Recap
Reference links
- Machine runner orchestrator installation and configuration
- Machine Runner Orchestrator 1.0.0 release note
- Self-hosted runner FAQs and Docker security guidance
- Self-hosted runner concepts and project restrictions
- Scaling self-hosted runners
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
