Adding Hosts

The hub holds no Docker socket of its own. Every machine that runs runner containers — including the one next to the hub — runs an agent that dials home over an authenticated WebSocket. The agent connects out, so there’s no inbound port to open, no SSH key, no VPN, and it works behind NAT. To grow your fleet, enroll more hosts.

Enroll a host

1. Start the enrollment.

   On the hosts page, choose Add host and give it a name like builder-01.

2. Optionally request the isolated runtime.

   Tick Install sysbox-runc on this host in the same dialog to run isolated runners on it; the installer sets it up alongside the agent. See Isolated runtime.

3. Copy the install command.

   The hub shows a one-time enrollment token baked into a single line:

   curl -fsSL <hub>/install/<token>.sh | sudo bash

4. Run it on the host machine.

   The installer auto-detects the package manager (apt or dnf) and architecture (amd64 or arm64), installs sysbox-runc if requested, pulls the public agent image (anonymous — no docker login), and runs it with the agent data volume, the Docker socket, and a read-only /:/host:ro bind mount for the host disk gauge.

5. Wait for it to connect.

   The agent dials the hub, the enrollment token is consumed and swapped for a long-lived agent token, and the host appears online within a few seconds.

Note

The agent pulls a published image and runs it; the hub never sends it code. The hub can later trigger the agent to pull a newer published version, but the operator stays in control of every update. See Updating Runaway.

Assign scale sets to the host

A new host adds capacity, but the hub won’t place runners there until a scale set targets it. Open the scale set, choose Edit hosts, check the new host, and save.

The reconciler distributes runners across every targeted host round-robin, respecting each host’s per-host cap. A single-host setup collapses to single-host behavior.

Running runners only on remote hosts

To have the hub own zero compute and run runners only on remote machines, leave RUNAWAY_LOCAL_AGENT_TOKEN unset when you deploy the hub. The hub then enrolls only the remote agents you add — the shape a public Coolify deploy uses.

Reliability notes

A flapping agent can’t double-spawn

When an agent reconnects, the hub re-scans that host’s Docker reality and rebuilds its runner records from what’s actually there. That scan runs under the reconciler’s lock, so an agent reconnecting repeatedly can’t produce duplicate records or phantom spawns.

A flaky host stays isolated

Per-host backoff means one misbehaving host doesn’t stall reconciliation of the others. A failing host backs off on its own schedule (per scale set, per host) while healthy hosts keep getting runners. Offline hosts are skipped, not redistributed onto.

Recovering a dead host

If a host is gone for good, the hosts page offers a force-delete that discards its orphaned runner records along with the host row. Use it only when the agent is never coming back; for a temporary outage, wait for it to reconnect.

Re-enrolling is non-destructive

Mint a fresh installer URL for an existing host from its detail page without wiping volume state — how you re-run the installer to pick up a new option, such as adding the isolated runtime to a host that didn’t have it.