Glossary
The terms you’ll meet across Runaway. Where a concept has its own page, the term links to it.
Architecture
Section titled “Architecture”Hub : The orchestrator and web UI — the single container you install. It’s the only decision-maker: it decides what runners should exist and where. It holds no Docker socket of its own.
Agent : A small container that runs next to each Docker daemon you want Runaway to drive. It dials out to the hub over an authenticated WebSocket and executes the hub’s commands — spawning, reaping, and inspecting containers. Agents make no decisions.
Host : A Docker machine running an agent. The hub distributes runners across all the hosts you’ve enrolled. Even the hub’s own machine is a host (with its own agent) when you run the bundled local agent.
Scale set
: A pool of ephemeral runners for one GitHub org or personal account, sized between minRunners and
maxRunners, with its own labels, cache volume, and runtime. Routing jobs to a scale set is done
by matching its labels in runs-on.
Reconciliation loop : The single path that creates or destroys runner containers. It runs on a timer, on Docker exit events, and after you change something — bringing the real world in line with what each scale set wants. Nothing else mutates Docker.
Runners
Section titled “Runners”Ephemeral runner
: A runner container that runs exactly one job, then is destroyed (AutoRemove: true) and replaced
by a fresh one. No state carries between jobs.
Idle / busy
: The status of a live runner. A 30-second GitHub poll splits running runners into idle (waiting
for work) and busy (running a job).
Warm pool / minRunners
: The floor of runners Runaway keeps ready even when there’s no work. Set it above zero to absorb
bursts without a cold-start wait.
Ceiling / maxRunners
: The most runners a scale set will scale up to under load. Set minRunners = maxRunners to pin a
fixed-size pool.
Scale-to-zero
: minRunners = 0. The pool shrinks to nothing when the queue is empty and scales back up when work
arrives.
Scaling
Section titled “Scaling”Demand
: How many runners a scale set should have right now, computed as busy + queued — runners currently
running jobs plus jobs waiting in the queue.
Polling vs. webhooks : Two ways the hub learns about demand. Polling asks GitHub every 30 seconds and works everywhere, including behind NAT. Webhooks are an optional, per-org opt-in that delivers a faster signal; polling automatically resumes if a webhook goes quiet or breaks.
Configuration
Section titled “Configuration”Custom env : Per-scale-set environment variables injected into every runner — handy for pointing package managers at a registry proxy you already run. Reserved auth and runner keys are blocked.
Cache volume
: The persistent /cache volume mounted into every runner in a scale set. Package stores, browser
binaries, and ecosystem caches survive across runs instead of round-tripping through GitHub’s
Actions Cache.
Shared-daemon runtime : The default runtime. Every runner on a host shares that host’s Docker daemon — fast and warm-cache-friendly.
Isolated (sysbox) runtime : An opt-in per-scale-set runtime that wraps each runner in sysbox’s user-namespaced nested Docker daemon. Each job gets a fresh inner daemon, so Docker layers and images don’t persist across runner generations — matching github-hosted semantics.
Identity and safety
Section titled “Identity and safety”Install id : A unique id each Runaway install stamps into every runner’s name and Docker label. It scopes all cleanup so two installs sharing a GitHub org or Docker host never deregister or remove each other’s runners.
Zombie sweep : A periodic cleanup that deregisters offline runners this install registered, so the GitHub UI stays tidy. It only touches runners carrying this install’s id, and a safety gate stops it from acting on a genuine correlation fault.
Orphan reaping : The reconciliation loop’s removal of runner containers that no longer belong to any known scale set — but only ones carrying this install’s id. Containers from other installs, or unmarked ones, are left untouched.
Enrollment
Section titled “Enrollment”Enrollment token : A single-use, short-lived token (15-minute TTL) you generate to enroll a new host. The agent presents it once on connect and trades it for a long-lived agent token.
Agent token : The long-lived, rotatable token an agent uses to authenticate to the hub after enrollment. It’s stored hashed and can be revoked from the UI.