opschain server restore
Included from Basic tier
opschain server restore <backup-dir>
Restore an embedded (SQLite) server from a directory written by
opschain server backup. The backup is verified first — every file in
manifest.json must match its recorded SHA-256 and size, and the manifest
format must be opschain-backup/v1 — then the SQLite store is copied into
place (stale -wal/-shm sidecars removed) and the blob tar is unpacked
over the blob root.
The server must be stopped. The next server start reconciles in-flight
state honestly: leases that died with the backup fail fast as runner_lost
(retriable), and queued steps dispatch again —
opschain server restore /backups/opschain-2026-10-14
restored /var/lib/opschain/opschain.db (42 blob(s), backup taken 2026-10-14T03:00:00Z)
start the server to reconcile: leases that died with the backup fail fast as runner_lost (retriable); queued steps dispatch again
The store and blob root are resolved as server start resolves them, so a
backup restores into whatever store the current config.yaml names.
PostgreSQL stores are refused with the same guidance as server backup
(the operator's own tooling owns those).
Flags
| Flag | Meaning |
|---|---|
--force | Overwrite an existing store and merge over a non-empty blob root. Without it an existing store — or a blob root that is not empty — refuses by name. With it, blob restore is a merge: blobs are content-addressed, so same-named entries are identical and extra local blobs survive. |
Named errors
backup verification failed: <reason>— a manifest file is missing, altered (<name> does not match its manifest entry) or the format is unsupported. Nothing has been touched.store <path> already exists — stop the server and pass --force to overwrite it (its WAL sidecars are removed too).the blob root <path> is not empty — pass --force to merge the backup's blobs over it, or move it aside first.- The PostgreSQL guidance (see
opschain docs cli/server-backup).
All exit 1.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Restore completed. |
| 1 | Verification failed, refused, or the restore failed partway. |
| 2 | Usage error — the backup directory argument is missing. |
See also
opschain docs cli/server-backup— what the directory contains, and why keys.env must be restored separately.opschain learn 8.1— backup and interchange.