Skip to content

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.

Terminal window
systemctl --user stop prism # macOS: launchctl bootout gui/$(id -u)/com.prism.router
cd ~/.prism
prism backup create
# backup created: data/backups/prism-backup-20261007T073554Z.tar
prism backup verify data/backups/prism-backup-20261007T073554Z.tar
# backup verified
systemctl --user start prism

With the Debian package:

Terminal window
sudo systemctl stop prism
sudo -u prism prism backup create --config /etc/prism/config.toml
sudo systemctl start prism

If 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)
  • 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 verify checks 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.

  1. Install the same or a newer Prism on the new machine and stop it.

  2. Copy the archive over and check it: prism backup verify ARCHIVE.

  3. Extract it into an empty state directory:

    Terminal window
    mkdir -p ~/.prism/data
    tar -xf prism-backup-20261007T073554Z.tar -C ~/.prism/data --exclude manifest.json
  4. 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.

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.