RunZero Documentation

Everything you need to know about configuring, running, and scaling your local GitHub Actions runner fleet with Docker containers, dedicated Linux Virtual Machines, and intelligent proxy caching.

Quick Start in 60 Seconds

RunZero deploys an autoscaler daemon alongside local caching proxies (apt-cacher-ng for Debian/Ubuntu, Verdaccio for npm, Athens for Go, and Docker Hub mirror).

# 1. Clone the repository
git clone git@github.com:el-j/run-zero.git
cd run-zero

# 2. Launch the interactive configuration wizard
make env

# 3. Build runner images (ARM64 + AMD64)
make build

# 4. (Optional for VM speeds) Build golden VM base template
make build-vm-base

# 5. Start the autoscaler and caching proxies in the background
make start

# 6. Stream live runner logs
make logs

Prerequisites

RunZero runs on macOS, Linux, and Windows with minimal system requirements:

• Container Runtime: OrbStack (recommended for macOS), Docker Desktop, or native Linux Docker.
• GitHub Personal Access Token (PAT): Classic PAT with repo scope (and admin:org if managing an Organization fleet).
• Hardware: Apple Silicon (M1/M2/M3/M4) or Intel/AMD x86_64 CPU, 4GB+ RAM.

Interactive Setup Wizard (make env)

Running make env invokes an interactive terminal wizard that asks for your token, account username, desired engine, and concurrency limit:

# Quick launch in your default web browser
make dashboard

# Or start the full fleet and navigate directly to:
open http://localhost:49505

# Personal scope
OWNER=your-username
# Organization scope (optional)
# ORG=your-org-name

# Token used by autoscaler API + billing lookups
ACCESS_TOKEN=ghp_xxx

# Optional polling cadence for billing panel
ACTIONS_BILLING_REFRESH_INTERVAL=300

# Start the Host VM Bridge daemon on the host
make bridge-start

# Check bridge daemon status and health
make bridge-status

# Stream bridge logs
make bridge-logs

# Stop the bridge daemon
make bridge-stop

Dual-Engine Fleet Architecture

Unlike traditional runner solutions that force you into a single execution model, RunZero offers a pluggable driver architecture:

🪐 OrbStack Linux VM Driver (RUNNER_BACKEND=orbstack-vm)

Spawns dedicated lightweight Linux machines via OrbStack and Apple Virtualization.framework. Provides full systemd support, unconfined Google Chrome sandboxing, background daemons, and internal Docker-in-VM capabilities. Automatically connects to host Verdaccio, Athens, and apt-cacher proxies via host.orb.internal.

🏗️ Golden VM Base Image (make build-vm-base)

To make VM boot times near-instant, make build-vm-base pre-bakes the shared toolchain into a golden base image (runzero-vm-base-<arch>). Subsequent VM jobs spin up in seconds by cloning the base image!

🐳 Docker Container Driver (RUNNER_BACKEND=docker)

Launches ultra-fast ephemeral containers powered by Docker Engine. Starts in ~0.3 seconds and consumes zero RAM when idle. Ideal for unit tests, linting, build pipelines, and JavaScript/Python workflows.

🪟 Windows WSL2 Driver (RUNNER_BACKEND=wsl2)

Runs native Linux runners directly inside Windows Subsystem for Linux 2 (Windows 10/11 and Windows Server) without requiring Docker Desktop.

🚀 Canonical Multipass Driver (RUNNER_BACKEND=multipass)

Universal cross-platform virtual machine backend using Canonical Multipass via QEMU, Hyper-V, or VirtualBox.

Hybrid Auto-Routing

With RUNNER_BACKEND=auto and AUTO_ROUTE_VM=true, you don't need to choose a single engine. The autoscaler inspects workflow labels and job names:

# Standard unit test runs in ultra-fast Docker container (~0.3s)
jobs:
  test:
    runs-on: [ self-hosted, local ]
    steps:
      - run: npm test

# Lighthouse / Browser E2E automatically routes to dedicated Linux VM!
jobs:
  audit:
    runs-on: [ self-hosted, local, browser ]  # Triggers: 'browser', 'e2e', 'lighthouse', 'systemd', 'vm'
    steps:
      - run: npx lhci autorun

APT & Package Proxy Caching

RunZero runs lightweight background caching proxy services so that neither your container image builds nor your CI runner executions waste bandwidth re-downloading packages from public registries:

Cargo has no single "index URL" environment variable the way pip/uv (PIP_INDEX_URL/UV_INDEX_URL) and Go (GOPROXY) do -- pointing it at kellnr requires a real ~/.cargo/config.tomlsource-replacement block, written automatically for both the Docker and OrbStack VM engines. pip also refuses a plain-HTTP index on any host other than localhost/127.0.0.1 unless it's explicitly trusted via PIP_TRUSTED_HOST, which both engines set automatically alongside PIP_INDEX_URLwherever the index isn't reached via localhost.

OrbStack VM Local Disk Caching

The proxies above cache package downloads over the network. Package managers also keep a local, already-extracted disk cache (~/.npm, ~/.cache/pip, ~/go/pkg,~/.cargo/registry, etc.), which for the Docker engine is a plain -v host:containerbind mount. An OrbStack VM is a real, separate guest filesystem with no such flag, but every non-isolated OrbStack VM automatically virtiofs-shares the entire host macOS filesystem into the guest at a fixed path,/mnt/mac<absolute-macOS-path>. RunZero's OrbStack driver uses this to bind-mount each host-side cache directory onto its container-style destination path inside the VM before the job runs, so cache data written by one ephemeral VM is really on host disk and visible to the next VM cloned for the same architecture.

Job Environment & the RUNZERO Marker

Every runner, on every backend, exports the same variables beforerun.sh, so every job step inherits them, the way GitHub's own images set theirs. Each one fixes a cache miss that was measured on real jobs:

On RunZero, actions/cache steps for node_modules, the pnpm store or Playwright browsers only duplicate, slowly and over the network, what the host already caches. Skip them with the marker; the same workflow keeps caching normally on GitHub-hosted runners:

- uses: actions/cache@v4
  if: env.RUNZERO != '1'
  with:
    path: ~/.cache/ms-playwright
    key: playwright-${{ hashFiles('pnpm-lock.yaml') }}

# The runner images already contain Playwright's system packages, so
# --with-deps only adds an apt-get update on RunZero.
- run: pnpm exec playwright install ${{ env.RUNZERO == '1' && '' || '--with-deps' }} chromium

If a job still needs apt-get, it goes through apt-cacher-ng. The runner images keep their package indices and skip translation files, soapt-get update fetches only what changed since the image was built. Repositories served over HTTPS (Microsoft, Docker) bypass the proxy.

Run make doctor to check all of this from inside a fresh runner. For each backend it reports the registry and store that npm, yarn and pnpm 10/11 resolve, the tool cache and Playwright mounts, proxy latency, cache sizes, host load, runner sizing, and whether the bridge and autoscaler run the code you have checked out.

Native-Arch Override (Apple Silicon)

A workflow that targets runs-on: [self-hosted, local, amd64]has to keep working on GitHub-hosted ubuntu-latest. On Apple Silicon, every such job runs under Rosetta emulation, which is several times slower for Node and browsers, even though most jobs (Node, pnpm, Playwright, Go) do not depend on the architecture.

With NATIVE_ARCH_OVERRIDE=all (or a list ofowner/repo names) RunZero serves those repositories'amd64 jobs with native arm64 runners, with no change to the workflow. The runner still carries the job's amd64 label, butRUNNER_ARCH inside it is ARM64, sosetup-node and Playwright fetch native binaries. x86-64 binaries and --platform linux/amd64 containers still run through Rosetta. The startup log, the job log line and the dashboard's routing card show when an override was applied.

Trade-off: a job that checks uname -m, or builds amd64 artifacts without --platform, gets arm64. Leave such repositories off the list. Jobs labelled rosetta orx86_64 are never moved, and the setting does nothing on amd64 hosts.

First-Level Dependencies & Upstream Tools

RunZero builds upon best-of-breed open-source virtualization and runtime platforms:

• OrbStack: Superfast, lightweight container engine and Linux Virtual Machine hypervisor for macOS.
• Docker Engine & Compose: Industry standard container runtime and service orchestration.
• apt-cacher-ng: High-performance caching proxy for Debian and Ubuntu APT package downloads.
• Verdaccio: Lightweight zero-config private npm proxy registry with web interface.
• Athens: Enterprise-grade Go module caching proxy server.
• NVM (Node Version Manager): Multi-version Node.js environment pre-baking Node 20, 22, and 24.
• Microsoft .NET SDK: Cross-platform .NET 8.0 SDK runtime for C# and F# builds.
• Playwright: Reliable end-to-end testing for modern web apps with pre-installed OS dependencies.

Zombie Runner Healing & Auto-Reconciliation

If an ephemeral runner machine is stopped abruptly mid-job (e.g. during workstation sleep or make stop), GitHub might mark it as offline but busy: true.

RunZero's autoscaler automatically reconciles zombie runners by cancelling stranded runs and unsticking GitHub's runner queue so jobs never hang.

Environment Variables Reference (.env)

Makefile Command Reference

make start          # Start Autoscaler and Proxy registries (apt-cacher, Verdaccio, Athens)
make stop           # Stop Autoscaler, Proxies, and cleanup active runners
make status         # Show status of services and active runner instances
make doctor         # Verify cache wiring from inside throwaway runners (no GitHub token needed)
make logs           # Stream live autoscaler logs
make test           # Run 85 unit tests directly (0.04s)
make test-suite     # Run Flake8 linter, Mypy type-checker, and Pytest coverage
make install-hooks  # Install pre-commit quality guard into .git/hooks/pre-commit
make pre-commit     # Run pre-commit quality guard manually with auto-fixes
make lint           # Run Flake8 linter and Mypy static type checker
make lint-fix       # Auto-fix Python formatting and strip trailing whitespace
make build-vm-base  # Build golden OrbStack VM base image for instant cloning
make website-dev    # Start Astro documentation website development server
make website-build  # Build Astro static website and synchronize to docs/
make verdaccio-ui   # Open Verdaccio NPM registry dashboard (http://localhost:49501)
make apt-cacher-ui  # Open apt-cacher-ng statistics report (http://localhost:49503/acng-report.html)
make clean-cache    # Clear shared package caches to reclaim disk space

Troubleshooting & FAQ

How do I test a workflow on Apple Silicon and AMD64?

Set RUNNER_ARCH=both in .env and specify runs-on: [self-hosted, local, arm64] or runs-on: [self-hosted, local, amd64] in your GitHub workflow YAML.

How does package caching work across containers and VMs?

RunZero exposes apt-cacher-ng on port 49503, Verdaccio on port 49501, and Athens on port 49500. Containers on host networking and VMs on virtualized bridges automatically route package downloads through these local proxies.