ARCHITECTURE // DUAL-ENGINE HYBRID CI v0.0.1

Zero Cloud Minutes.
Zero K8s Bloat.
Zero Idle Waste.

The hardware-optimized, autoscaling GitHub Actions runner fleet for developer workstations. Instantly launches ephemeral Docker containers (~0.3s) for rapid builds, or provisions dedicated Linux Virtual Machines with full systemd and unconfined Chrome sandboxing for browser E2E tests.

⚡ INITIALIZE FLEET READ ARCHITECTURE DOCS →

CLI_PROMPT // AUTO_DAEMON

01 02 03 04 05 06 07 08

# 1. Clone repository and run interactive setup wizard
❯ git clone git@github.com:el-j/run-zero.git
❯ cd run-zero && make env

# 2. Launch Autoscaler & local proxy registries
❯ make start

# 3. Stream real-time ephemeral runner telemetry
❯ make logs

// SYSTEM_CAPABILITIES

Engineered for High-Performance Workstations

Direct host acceleration with zero Kubernetes control plane overhead and automated registry proxy caching.

⚡

Dual-Engine Fleet

Execute jobs in ephemeral Docker containers (~0.3s boot, 20MB idle RAM) or dedicated Linux VMs (OrbStack / WSL2) with full systemd and unconfined Chrome sandboxing.

DRIVER: DOCKER + VM

🧠

Hybrid Auto-Routing

Inspects workflow labels in real time and automatically routes jobs with browser, e2e, lighthouse, or systemd labels to dedicated VMs while keeping unit tests in fast containers.

ROUTING: ZERO-CONFIG

🍏

Native ARM64 + Rosetta AMD64

Run native Apple Silicon ARM64 binaries at bare-metal speed, or run x86_64 AMD64 Docker containers simultaneously using OrbStack's Rosetta 2 acceleration.

ARCH: MULTI-PLATFORM

📦

APT, Verdaccio & Athens Caching

Integrated caching proxies for Debian/Ubuntu (apt-cacher-ng :49503), npm (Verdaccio :49501), Go (Athens :49500), and Docker Hub.

PROXIES: APT + NPM + GO + DOCKER

🌐

Adaptive Rate-Limiting & Zombie Healing

Smart discovery filters active repositories, auto-cancels orphaned runs pinned to dead runners, and monitors GitHub API quota headers to guarantee zero rate-limit bans.

QUOTA: PROTECTED

🔒

Zero Kubernetes Overhead

No K8s control plane, no etcd, no Helm charts, and no cert-manager consuming 3.5GB of your laptop's RAM before a single job even starts.

IDLE RAM: ~20MB

📊

Real-Time Web UI Dashboard

Instant browser visibility at :49505 with live Server-Sent Events (SSE). Track runner stopwatches, GitHub API quotas, hybrid routing metrics, and stream daemon logs.

PORT: :49505 // LIVE SSE

🌉

Host VM Bridge

Secure control daemon at :49504 enabling containerized autoscalers to manage host-native OrbStack, WSL2, and Multipass VM lifecycles seamlessly.

PORT: :49504 // VM CONTROL

🛡️

100% Mutation & Unit Tested

Verified with 155 unit tests, 0 Flake8 lint warnings, 100% Mypy static type safety, and Mutmut mutation testing across all drivers.

QUALITY: 155 TESTS VERIFIED

🟢

Unified CI Toolchain

Single source of truth toolchain script: pre-installed Node.js 20/22/24 LTS via nvm, .NET SDK 8.0, Git LFS, PostgreSQL client, and Playwright OS dependencies.

TOOLCHAIN: READY

// LIVE_OBSERVABILITY_INTERFACE

Real-Time Fleet & Telemetry Dashboard

PORT :49505

Zero external SaaS dashboards. RunZero provides a built-in, 100% self-hosted real-time Web UI for instant fleet status, hybrid routing telemetry, cache analytics, and log streaming.

🔒 http://localhost:49505 ● LIVE SSE STREAM

make dashboard

ACTIVE RUNNERS

3 / 10 max

GITHUB API QUOTA

4,982 / 5,000

HYBRID ROUTING

62% Docker · 38% VM

PROXY CACHE USAGE

14.8 GB saved

⚡ ACTIVE RUNNER FLEET AUTO-SCALE ENABLED

DOCKER

local-runner-arm64-1

el-j/run-zero · 00:42s

RUNNING JOB

ORBSTACK VM

local-runner-amd64-vm-2

el-j/webapp-e2e · 01:18s

PLAYWRIGHT E2E

DOCKER

local-runner-arm64-standby

fleet-standby · 00:05s

IDLE (MIN 1)

🧠 HYBRID ROUTING BREAKDOWN ZERO-CONFIG

Docker Containers (Unit Tests & Builds) 128 jobs (62%)

Services / DIND Workflows (Auto-VM) 44 jobs (21%)

Playwright / Browser E2E (Auto-VM) 26 jobs (13%)

Systemd / Custom Labels (Auto-VM) 8 jobs (4%)

🧹 Clean Caches ⚙️ Host VM Bridge :49504

📡

Server-Sent Events (SSE)

Ultra-low overhead real-time updates broadcast instantly to your browser without polling.

🌉

Host VM Bridge (:49504)

Containerize your autoscaler daemon while retaining full OrbStack, WSL2, and Multipass VM capabilities.

📦

100% Offline & Self-Hosted

Zero external telemetry or cloud dependencies. All UI fonts, assets, and metrics stay on your machine.

// DISPATCH_LOGIC

Hybrid Auto-Routing Engine

Zero cluster switching. RunZero inspects your job labels and dispatches either to ultra-fast container runtimes or dedicated virtual machines.

EPHEMERAL_DOCKER Unit Tests & Builds

~0.3s BOOT 20MB IDLE

123456

jobs:
  test-suite:
    runs-on: [ self-hosted, local ]
    steps:
      - uses: actions/checkout@v7
      - run: npm test

⚡ RUNTIME: CONTAINER // SOCKET: HOST // ISOLATION: CGROUP

DEDICATED_LINUX_VM Browser E2E & Systemd

FULL OS SYSTEMD

123456

jobs:
  browser-audit:
    runs-on: [ self-hosted, local, browser ]
    steps:
      - uses: actions/checkout@v7
      - run: npx lhci autorun

🛡️ RUNTIME: VIRT_FRAMEWORK // SYSTEMD: ACTIVE // CHROME: UNCONFINED

// COMPATIBILITY_MATRIX

Execution Engine Matrix

RunZero adapts to your operating system, supporting containers and full virtual machines across macOS, Windows, and Linux.

Engine Driver	Host OS	Execution Mode	Key Strengths
🪐 OrbStack (Recommended)	macOS (Apple Silicon & Intel)	Containers & Linux VMs	Instant boot, golden VM cloning, Rosetta 2 x86_64 acceleration, full systemd.
🐳 Docker Desktop	macOS, Windows, Linux	Containers	Universal cross-platform container support.
🪟 Windows WSL2	Windows 10/11 & Server	Native Linux VMs	Native Linux execution without requiring Docker Desktop on Windows.
🚀 Canonical Multipass	macOS, Windows, Linux	Virtual Machines	Universal cross-platform Ubuntu VMs via QEMU / Hyper-V / VirtualBox.
🐧 Native Linux Docker	Ubuntu, Debian, Arch, Homelabs	Native Containers	Zero VM layer, direct kernel speed for homelab servers.

// COMPETITIVE_ANALYSIS

Why Not ARC or Nektos/act?

RunZero eliminates enterprise K8s control plane bloat while running real production GitHub webhook queues on your local machine.

Metric / Feature	⚡ RUNZERO	🏢 ACTIONS RUNNER CONTROLLER (ARC)	🎭 NEKTOS / ACT	📦 STATIC DOCKERFILE
Target Machine	Local Mac / Workstation	Enterprise Cloud K8s Fleet	Local CLI Scratchpad	Single Homelab Server
Idle RAM Footprint	~20 MB (0 MB at idle)	1.5 GB – 3.5 GB (K8s Control Plane)	0 MB (Manual CLI only)	~500 MB+ (Idle runner daemon)
Execution Runtime	Dual-Engine (Docker + VM)	Containers Only (K8s Pods)	Containers Only	Container Only
Real GitHub Queue Listener	Yes (Adaptive polling)	Yes	No (Local mock only)	Yes
Multi-Repo Discovery	Yes (All user repos auto-scaled)	No (Orgs only)	N/A	No (1 repo per runner)
Multi-Arch (Apple Silicon + Rosetta)	Yes (Rosetta 2 acceleration)	Complex (Node taints/specs)	Partial	No (Fixed architecture)
Local Caching Registries	Yes (Verdaccio + Athens + Toolcache)	No (Requires K8s PVCs/NFS)	No	No
Setup Time	< 60 Seconds (`make start`)	Heavy Helm / CRD setup	1 Command	Moderate

Zero Cloud Minutes. Zero K8s Bloat. Zero Idle Waste.