Backups and restore
What to back up — MongoDB and ENCRYPTION_KEY above all — with tested commands, how to check a backup, and what happens after a restore.
Self-hosted
| What | Why | How |
|---|---|---|
| MongoDB | Source of truth: users, organizations, projects, tasks, events, audit, capabilities, encrypted secrets | mongodump / mongorestore |
ENCRYPTION_KEY | Decrypts organization secrets and users' two-factor secrets | Your secrets manager, separately from the database backup |
JWT_SECRET | Signs access tokens | If lost, users sign in again |
| Redis | Dispatch signals only | Not required: the scheduler rebuilds from MongoDB |
| Artifacts | Screenshots and reports | Your usual volume or bucket backup |
| Worker data | Per-machine config and credentials | Usually not backed up: re-pair a worker instead |
Keep the key
Without ENCRYPTION_KEY, a restored database has unreadable secrets and users with two-factor authentication
cannot sign in. After a key rotation, keep the old key as long as you keep backups made before it.
Back up MongoDB
mongodump and mongorestore are part of the MongoDB Database Tools, a separate download from the server.
docker compose exec -T mongo mongodump --archive --gzip --db agent_orchestration > backup-$(date +%F).archive.gz
# restore
docker compose exec -T mongo mongorestore --archive --gzip --drop < backup-2026-09-27.archive.gzmongodump --uri "$MONGODB_URI" --db agent_orchestration --archive=backup.archive.gz --gzip
mongorestore --uri "$MONGODB_URI" --archive=backup.archive.gz --gzip --dropOn Kubernetes, the Helm chart can run nightly dumps: see Kubernetes.
Check a backup before you need it
Restore it into a separate database on the same server; this touches nothing in use:
mongorestore --uri "$MONGODB_URI" --archive=backup.archive.gz --gzip \
--nsFrom='agent_orchestration.*' --nsTo='agent_orchestration_restore_check.*'
# inspect, then drop agent_orchestration_restore_checkAfter a restore
- Restart the control plane with the same
ENCRYPTION_KEY. Migrations apply automatically. - Tasks that were running when the backup was taken recover by lease expiry: requeued from their last
checkpoint, or marked
RECOVERY_REQUIRED, depending on policy. - Workers reconnect by themselves. A worker paired after the backup is unknown to the restored database: pair it again.
- Restoring an older backup removes audit entries created after it; keep audit exports for a continuous record.
Verified
The procedure without Docker is exercised by an automated drill (MongoDB Database Tools 100.19.0, MongoDB 8.3): back up, check, drop, restore, restart; sign-in with two-factor, secrets, indexes, timelines, counts and lease recovery all check out. The Docker Compose form of the commands has not yet been run.