Updating Runaway

The hub and the agent are released together and speak an exact protocol version with no backward-compatibility window. Always upgrade them as a pair and pull matching runaway and runaway-agent tags.

Caution

A release that changes the wire protocol can’t adopt runner containers spawned by the old version. Check the release notes: if they say to drain first, set every workload’s minRunners and maxRunners to 0, let in-flight runners finish and auto-remove, and confirm zero runners in the dashboard before you upgrade.

Upgrade the hub

1. Pull and restart.

   docker compose pull && docker compose up -d

2. Let the entrypoint migrate.

   On boot the entrypoint runs prisma migrate deploy before the hub starts serving. Migrations are additive, so a forward upgrade doesn’t rewrite your existing data.

Danger

SQLite is single-writer. Never run two hub containers against one data volume — use recreate, not a rolling restart. A second container on the same volume exits cleanly rather than corrupting state, but don’t rely on that as a deploy strategy.

Update an agent

An agent never updates its own code, and the hub never sends it code. What the hub triggers is a docker pull of a newer published image. You start the update from the hub UI; the hub names only a version, never a repo or artifact; the agent pulls its own image at that version, forward-only, and runs only published Runaway-authored code. Updates are operator-confirmed, never automatic.

Note

You can also pull the agent image by hand on the host and let it reconnect, instead of triggering from the UI.

Keep the pair matched

Run the hub and every agent on the same release. After you upgrade the hub, update each agent to the matching version. Until you do, a version-behind agent is held on a restricted connection: it won’t be scheduled onto, but stays reachable so you can trigger its update from the UI.