Skip to main content
A complete backup strategy for a self-hosted sovseal deployment covers two independent data structures: the Postgres relational database and the LanceDB files on each client device. Both must be backed up to guarantee full recoverability — Postgres holds the replicated encrypted snapshot chain, while LanceDB holds the live local memory state and sync queue. This guide walks through both backup methods, restoration procedures, and the crash-recovery behaviour built into the sovseal client.
Your encryption keys are never stored on the server. If you lose the OS-keychain master key (or the SOVSEAL_KEY_FALLBACK=file key file on headless machines), every snapshot — local and replicated — becomes permanently unreadable. There is no escrow and no reset. Export and securely store your key material before any infrastructure migration or hardware change.

​
Postgres Schema and Snapshot Backups

Self-hosted sovseal runs its Postgres schema on your own Supabase project — there is no local database container to manage. All API key hashes, sequence numbers, and AES-256-GCM encrypted snapshot payloads live there. Use Supabase’s own backup tooling, or pg_dump directly against the project’s connection string, for hot logical backups.
Supabase projects on paid plans include automatic daily backups and point-in-time recovery (PITR) out of the box — check your project’s Database → Backups settings before building custom tooling. The commands below are for teams that want an independent, self-managed copy.

​
Create a Logical Backup

Or use the connection string directly from your Supabase project settings. Schedule this in a cron job or CI pipeline. Because every payload column contains ciphertext, the dump file itself is safe to store in ordinary object storage (S3, R2, etc.) for an additional layer of protection.

​
Restore from a SQL Dump

1

Provision a clean target

Restoring into the same project risks colliding with live traffic. For a real disaster-recovery drill, restore into a fresh Supabase project and re-point supabase link at it once verified.
2

Import the backup file

3

Redeploy the function

Re-run supabase functions deploy v2-agent-state so the function’s connection pool picks up the restored schema cleanly.

​
Local LanceDB Snapshot Backups

Each client device stores the live memory database at ~/.sovseal/db/. LanceDB uses an append-only Arrow transaction log, so a directory copy produces a consistent snapshot even if taken while the process is running.

​
Back Up the Database Directory

Store this archive alongside your Postgres dump. If you override the database location with SOVSEAL_DB_DIR, substitute that path.

​
Restore LanceDB from Archive

Restart the agent after extraction. On next boot, the SDK re-opens the restored database and resumes sync from the last synced sequence number.

​
Crash Recovery via Lineage Replay

If a client device loses its local LanceDB state (disk failure, accidental deletion, fresh machine), the sovseal SDK can reconstruct the memory database from the replicated snapshot chain in Postgres without any manual intervention.
1

Restore config.json

Place the client config file at ~/.sovseal/config.json with the original project_id and endpoint. The file must not contain key material — that lives in the OS keychain:
2

Restore the master key

Re-import the master key into the OS keychain (macOS example):
On Linux, use secret-tool store --label="sovseal" service sovseal username master. On headless machines with SOVSEAL_KEY_FALLBACK=file, copy the backup key file to ~/.sovseal/ and set permissions to 0600.
3

Rebuild local state from the replication log

This step is not automatic. Neither SDK repopulates the local database for you on boot — restore() and lineage() are primitives, and reconstructing state from them is a pattern you implement, the same way Verified Semantic Recall is a pattern you implement on top of restore().
Walk client.lineage({ agentId }) to get the sequence of prior snapshots, then for each one: restore() it, fetch the ciphertext, decryptJson it, and re-derive the hash to compare against receipt.client_payload_hash before trusting it — exactly the VSR pattern. Write each verified payload back into a fresh local LanceDB instance yourself.
If you restore a Postgres backup that predates recent client writes, the parent-snapshot chain for those later writes will not resolve — lineage() walks will stop at the restored point. Memories written after the backup date exist only in a surviving LanceDB archive on the device that wrote them, if one exists.

​
Key Backup Best Practices

Because key loss is irreversible, treat your encryption keys with the same care as private signing certificates:
  • Export the master key from the OS keychain immediately after first setup and store it in an offline, encrypted vault (e.g. a hardware security key or air-gapped secrets manager).
  • For SOVSEAL_KEY_FALLBACK=file deployments, include ~/.sovseal/ in your off-device backup rotation alongside the LanceDB directory.
  • Never commit key material to version control or include it in container image layers.
  • Rotate the master key only through the sovseal re-encryption workflow — not by deleting and regenerating it, which would invalidate all existing snapshots.