Backup and migration
prism backup create copies Prism’s state into one tar archive. Prism must
be stopped: the command opens every database read-only and fails while a
running Prism holds one open.
Create a backup
Section titled “Create a backup”systemctl --user stop prism # macOS: launchctl bootout gui/$(id -u)/com.prism.routercd ~/.prismprism backup create# backup created: data/backups/prism-backup-20261007T073554Z.tarprism backup verify data/backups/prism-backup-20261007T073554Z.tar# backup verifiedsystemctl --user start prismWith the Debian package:
sudo systemctl stop prismsudo -u prism prism backup create --config /etc/prism/config.tomlsudo systemctl start prismIf Prism is still running, the command stops with
backup create failed: backup accounts.db: stop Prism before backing up: timeout
and exit code 1.
| Option | Effect |
|---|---|
--config PATH |
config that names the state directory (default config.toml in the current directory) |
--storage DIR |
the state directory itself, instead of --config |
--output PATH |
archive path; default <storage.dir>/backups/prism-backup-<UTC time>.tar, mode 0600 |
--include-secrets |
also copy stored provider keys and the console token (below) |
What the archive holds
Section titled “What the archive holds”- the routing, accounts and quality-prior databases (request history, users, connections, settings);
- settings saved in the console, learned parameter rules, request policies, price and model catalogues;
- the migration backups the databases refer to;
manifest.json: the Prism version, each database’s schema version, and the size and SHA-256 of every file.prism backup verifychecks them before it opens any database.
Without --include-secrets the archive holds no provider keys. With it, the
archive also contains the stored provider keys, the key that encrypts them
(master.key) and the console token. Anyone with the file can read them:
keep such an archive offline.
Move Prism to another machine
Section titled “Move Prism to another machine”-
Install the same or a newer Prism on the new machine and stop it.
-
Copy the archive over and check it:
prism backup verify ARCHIVE. -
Extract it into an empty state directory:
Terminal window mkdir -p ~/.prism/datatar -xf prism-backup-20261007T073554Z.tar -C ~/.prism/data --exclude manifest.json -
Start Prism.
Do not extract over an existing state directory. The archive keeps the
directories that hold secrets readable only by their owner, which Prism
requires at start. If the archive was made without --include-secrets,
connect the providers again in the console after the move.
Before an upgrade
Section titled “Before an upgrade”An update from the console or prism update takes its own snapshot of the
state directory and restores it on rollback
(Update Prism). A backup made with
prism backup create --include-secrets before a manual upgrade or a package
upgrade lets you return to the previous state by hand.