Data and backups
Back up the database and configuration. Sandbox files and source-system data are outside the Orpheus PostgreSQL database.
| Preserve | Purpose |
|---|---|
| PostgreSQL | Sessions, runs, accepted messages, profiles, accounts and encrypted API keys |
ENV_ENCRYPTION_KEY | Decrypt stored environment values and model API keys |
orpheus.toml and Mattermost workflows | Reproduce configuration |
| GitLab review workflows and connector settings | Restore project routing, review policies and connection settings |
| Secrets and SAML files | Service connections and user sign-in |
| S3 credential store | Account authorization files |
If you use Space, back up its separate database too. It stores schedules, occurrence history and browser sessions. Full agent answers remain in the Orpheus database.
PostgreSQL backup
From the example Compose directory:
docker compose exec -T db pg_dump -U orpheus -d orpheus -Fc > orpheus.dumpKeep a protected copy away from the server. Test recovery into a separate empty database, not over the live database:
pg_restore --no-owner --no-acl --dbname="$RESTORE_DATABASE_URL" orpheus.dumpInstall PostgreSQL client tools for this command. RESTORE_DATABASE_URL must point to a test database. Preserve the encryption key and configuration corresponding to the backup.
Restored history does not recreate a deleted sandbox. Do not run a restored worker alongside production against the same tasks. Finished documents and comments should remain in the destination system.
docker compose down preserves the volume. down -v removes it.
Space database
From examples/space:
docker compose exec -T db pg_dump -U orpheus_space -d orpheus_space -Fc > orpheus-space.dumpRestore this backup to a separate Space database. Keep the test Space worker stopped so restored schedules cannot submit work to production Orpheus.