Configuring Scale Sets

A scale set is a pool of ephemeral runners attached to one GitHub organization or personal account. Everything Runaway needs to spawn a runner lives on it. Create one from the Add scale set dialog; edit it later from /scale-sets/<id>.

Note

When a default changes between versions, existing scale sets keep their prior behaviour — only newly created ones pick up the new default. Settings below note where this applies.

Organization or account

The connected GitHub organization or personal account this pool serves. The account must already be added with a valid classic PAT — see the quickstart. One account can back many scale sets; one scale set serves exactly one account.

Runner image

The Docker image Runaway spawns for each runner. The default is a myoung34/github-runner tag; the image registers itself with GitHub using your PAT and runs a single job before exiting.

If your image lives in a private registry, attach a pull credential — see Private runner images.

Sizing: minRunners and maxRunners

Runaway sizes the pool to demand between two bounds:

• minRunners — the warm floor kept ready even when the queue is empty.

• maxRunners — the ceiling Runaway scales up to under load.

• Scale to zero — minRunners = 0. No runners sit idle; the pool spins up when work arrives.

• Warm pool — minRunners = N keeps N runners ready, trading idle capacity for lower start latency.

• Fixed pool — minRunners = maxRunners pins the pool to a constant size.

For how demand is measured, see Autoscaling.

Labels and job routing

GitHub routes a job to a runner when the job’s runs-on labels are a subset of the runner’s labels. Give each scale set a distinct label and match it in your workflow:

jobs:
  build:
    runs-on: [self-hosted, my-label]

Tip

self-hosted is always implied — every Runaway runner carries it, so you don’t need to add it to a scale set’s labels. Use labels as the routing primitive between scale sets: distinct labels keep two pools from racing for the same jobs.

Docker socket (Docker-in-Docker)

Mounting the host Docker socket into runners is opt-in. New scale sets do not mount /var/run/docker.sock. Tick Mount Docker socket inside runners when your jobs build or run container images. For a true isolated Docker daemon per runner, use the isolated runtime instead (below).

Caution

When the socket is mounted, containers your job creates spawn as siblings on the host daemon — not nested inside the runner. See Writing workflows for the implications.

Runtime

• shared-daemon (default) — every runner on a host shares that host’s Docker daemon. Fast and warm-cache-friendly; the right default for homelab use.
• isolated-sysbox — wraps each runner in a user-namespaced nested Docker daemon, so each job gets a fresh inner daemon and everything inside it is discarded on exit.

See Isolated runners (sysbox) for the full tradeoffs and host setup.

Image pull policy

Controls when Runaway pulls the runner image before spawning:

• IfNotPresent — pull only when the image isn’t already on the host.
• Always — pull on every spawn.
• TtlHours — pull only if the last pull is older than the configured TTL (in hours). Keeps floating tags like :latest fresh without paying the pull cost on every spawn.

New scale sets default to TtlHours with a 24-hour TTL; existing scale sets preserve their prior pull behaviour. A pull failure hard-fails the spawn for that pass with a clear per-host error — Runaway never silently falls back to a stale cached layer. See Private runner images for credential-backed pulls.

Custom environment variables

A JSON record of extra environment variables injected into every runner — chiefly for pointing package managers at your own registry proxies. See Custom environment variables for the validation rules and merge order.

Private image credentials

Attach an encrypted registry credential to pull a runner image from a private registry. See Private runner images.

Target hosts and per-host caps

Assign the scale set to one or more enrolled hosts from Edit hosts. The scheduler distributes runners across every targeted host round-robin, bounded by a per-host cap. See Running multiple hosts.

Note

If no hosts are assigned, the scale set has nowhere to spawn runners. A single-host install targets the bundled local host by default.

Related

Custom environment variables

Caching

Private runner images

Isolated runners (sysbox)