Backups and recovery

Runaway gives you two ways to back up the hub:

• An encrypted backup file you export from the UI — portable, passphrase-protected, and the right tool for migrating to new hardware or seeding a second hub.
• A full copy of the data volume — everything on disk, for off-box disaster recovery.

Export an encrypted backup

From Settings → Backup & restore, choose Export backup, set a passphrase, and the hub downloads a .runaway-backup file.

Caution

The passphrase is the only thing protecting the secrets in the file, and it cannot be recovered. Store it in a password manager — lose it and the backup is unusable.

The file holds your configuration and identity:

| Included | Not included | |---|---| | Organizations and credentials (PATs) | Runner containers — rebuilt automatically on restore | | Scale sets and registry credentials | Event and job history — opt-in checkbox, off by default | | Hosts and their agent tokens | | | Install identity and the admin account | |

Secrets are re-wrapped under your passphrase rather than the hub’s RUNAWAY_MASTER_KEY, so a backup restores onto a hub with a different master key. That is what lets it migrate to new hardware. Turn on Include event & job history only if you need the observability log; it makes the file larger.

Restore from a backup file

Restore on a fresh hub or over a running one.

1. Open the restore flow. On a new hub, the setup screen offers Restore from a backup. On a running hub, use Settings → Backup & restore → Restore — it overwrites the current configuration, so it asks you to type a confirmation first.

2. Upload the file and enter the passphrase. Runaway previews what the backup contains before it changes anything.

3. Choose how to handle install identity:

   | Mode | Use it when | Effect | |---|---|---| | Move | Migrating to new hardware | Keeps the same install identity. Decommission the old hub first. | | Clone | Standing up a test or staging copy | Mints a fresh identity, so it runs safely alongside the source. |

4. Restart the hub. A restore always needs a restart to take effect.

5. Sign in with the admin credentials from the backup. Agents reconnect on their own, and their runners are re-adopted.

Caution

Move carries the same install identity to the new hub. Two live hubs sharing one identity fight over the same runners — shut the source hub down before bringing the restored one online. Use Clone when both need to run at once.

Full-volume backups

All hub state lives in one volume mounted at /app/data: the SQLite database and its write-ahead log. A copy of that volume plus the master key rebuilds the hub byte-for-byte.

On every startup the entrypoint snapshots the database into /app/data/backups/ before running migrations, keeping the last five:

• Directory/app/data

  • app.db SQLite database
  • app.db-wal write-ahead log
  • Directorybackups/ last 5 pre-migration snapshots

    • …

These snapshots recover from a migration failure — they are not a disaster-recovery backup, because they live in the same volume. If the volume is lost, the snapshots go with it. Keep an off-box copy of the volume on whatever schedule fits your data.

Caution

For a volume restore, the most important thing to keep is RUNAWAY_MASTER_KEY. It is not stored in the data volume — it comes from the hub’s environment — and it encrypts every GitHub token at rest. A volume-restored database is only usable with the same key it was encrypted under. (The encrypted backup file above is different: it re-wraps secrets under your passphrase, so it does not need the original key.)

To restore a volume:

1. Stop the stack so nothing is writing to the database.

2. Restore the volume or the database file from your off-box backup into /app/data.

3. Set the same RUNAWAY_MASTER_KEY the data was encrypted under.

4. Start the stack again. The entrypoint runs migrations and serves the restored state.

Note

SQLite is single-writer. Restore into a stopped stack and run a single instance — never two containers against the same volume.

What’s next

Docker Compose deploy The data volume and how the stack is laid out.