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.

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 on its own, and the hub never sends it code. What the hub can do is trigger an agent to pull a newer published image:

• You start the update from the hub UI.
• The hub names only a version — never a repo or an artifact.
• The agent pulls its own image at that version, forward-only (it will never downgrade).
• The agent runs only published, Runaway-authored code; nothing the hub supplies executes on the host.

Updates are always operator-confirmed, never automatic. The hub triggers; you decide.

Note

A version-behind agent stays reachable on a restricted connection precisely so you can trigger its update from the UI. If you’d rather, you can also pull the agent image by hand on the host and let it reconnect.

Keep the pair matched

The supported state is “hub and every agent on the same release.” After upgrading the hub, update each agent to the matching version. A version-behind agent is held on the restricted connection until you do — it won’t be scheduled onto, but stays reachable for the update trigger.