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.
Workload
: A pool of ephemeral runners for one GitHub org or personal account — its targeting (labels, name
prefix), sizing (minRunners / maxRunners), runtime, and cache key. It references a runner
profile for the runner’s shape. Routing jobs to a workload is done by matching its labels in
runs-on.
Runner profile : The reusable shape of a runner — image, memory and CPU limits, custom env, pull policy, and an optional registry credential. Defined once and referenced by many workloads.
Scale set : Former name for a Workload.
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 workload 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 workload 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 workload 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 breaks.
Configuration
Section titled “Configuration”Custom env : Environment variables on a runner profile, 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
: A persistent /cache volume mounted into every runner. It belongs to the host and is selected by
cache key. Package stores, browser binaries, and ecosystem caches survive across runs instead of
round-tripping through GitHub’s Actions Cache.
Cache key : An optional string on a workload that picks which host-owned cache volume its runners mount. No key shares one cache per org on a host; a key gives a separate warm cache. Different orgs never share.
Runtime
: The isolation tier on a workload, one of none, shared-daemon, dind, isolated-sysbox, or
isolated-kata — from no Docker access to a per-runner VM. none is the default. See the
runtime ladder.
Host runner budget : An optional ceiling on a host’s runner count, shared by all workloads scheduled on it. Floors are honored first, then the remaining budget is split across workloads in proportion to demand.
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 workload, 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.