Backup & Export

Sophon's backup system covers two use cases: routine backups for disaster recovery, and one-off exports for migration. Compliance-driven data extraction (right-to-erasure, DSAR) is covered under Compliance.

A Sophon backup is a full snapshot of the data directory (SOPHON_DATA, ~/.sophon by default): a zip archive plus a manifest listing every file with its SHA-256 hash, so restores can be verified before they touch anything.

What's in a backup

Everything the data directory holds:

• Configuration — appsettings.json overrides, channel config, MCP config
• Agents — SOUL.md, BOOT.md, HEARTBEAT.md, TOOLS.md, AGENTS.md, tool allowlists
• Workflows — definitions + version history
• Memory — all long-term entries and daily logs
• Documents — raw files + extracted text
• Skills — installed skills and their versions
• Cron jobs — definitions
• Security material — security/vault.key and the encrypted credential stores it protects
• SQLite database (Personal tier) — chats, tasks, approvals, audit entries

Excluded to keep archives lean: previous backups (backups/), sandbox workspaces, data/cache, and .log / .tmp / .lock files.

Creating a backup

Dashboard

Since v1.15, the Dashboard backup page at Settings → Backup manages data-directory backups end to end: create a backup, watch it run, browse existing snapshots, and delete old ones. Restore remains CLI-only.

Creation is asynchronous: the Gateway accepts the request and runs the backup as a background job, so the browser never waits on a multi-gigabyte archive. The page shows live per-file progress, survives a page reload mid-backup, and the run also appears in task activity. Only one backup runs at a time — a second create request while one is in flight is rejected.

Every backup route requires the manage-settings permission, because a backup contains every user's data — not just the caller's.

Snapshots are written server-side to <data-dir>/backups/snapshots/.

CLI

# Quick unversioned zip of the data directory
sophon backup --output backup.zip

# Versioned snapshot with an integrity manifest — same format the Dashboard creates
sophon snapshot --description "pre-upgrade"

# Manage snapshots
sophon snapshot-list
sophon snapshot-delete sophon-snapshot-20260729-031500

Prefer sophon snapshot over the plain sophon backup zip — the manifest is what makes verified restores possible.

Scheduled backups

Sophon does not schedule backups itself. Use your host's scheduler to snapshot on a cadence:

# crontab: nightly snapshot at 03:00 server time
0 3 * * * sophon snapshot --description "nightly"

Prune old snapshots with sophon snapshot-delete (or from the Dashboard) — retention is not automatic.

Backup structure

<data-dir>/backups/snapshots/
├── sophon-snapshot-20260729-030412.zip            # full copy of the data directory
└── sophon-snapshot-20260729-030412.manifest.json  # inventory + integrity hashes

The manifest records every file's path, size, and SHA-256 hash, plus a hash of the archive itself. The zip's internal layout mirrors the data directory, so in a pinch it can be inspected — or extracted — with standard tooling.

Restoring a backup

Restore is deliberately CLI-only — it runs on the host, not over HTTP. Stop the Gateway before restoring.

# From a plain backup zip — overwrites files in the data directory after confirmation
sophon restore backup.zip

# From a versioned snapshot — verifies integrity first, then restores
sophon snapshot-restore \
  ~/.sophon/backups/snapshots/sophon-snapshot-20260729-030412.zip \
  ~/.sophon/backups/snapshots/sophon-snapshot-20260729-030412.manifest.json

sophon snapshot-restore refuses to proceed if any file fails its manifest hash check, and it creates a pre-restore backup before writing anything, so a bad restore can be backed out.

Migration pattern

Moving from one Sophon instance to another:

1. Source host: sophon snapshot --description "migration"
2. Transfer the archive and its manifest securely — remember, the archive contains live credentials.
3. Destination host: fresh install, then sophon snapshot-restore <archive> <manifest>.
4. Start the Gateway. Because vault.key travels with the data directory, encrypted credentials and channel tokens keep working.
5. Pro/Enterprise: migrate PostgreSQL / Qdrant separately (see Self-Hosting → Backup & Upgrade).
6. Rotate any tokens if the archive transited storage you don't fully control.

Off-host storage, encryption & retention

Sophon writes backups to local disk and does not manage their lifecycle. Ship them off-host with your own tooling — aws s3 cp, azcopy, rclone, scp — and use your storage provider's lifecycle policies (S3 lifecycle rules, Azure Blob retention) to age out old backups:

# Encrypt, then ship
gpg --symmetric --cipher-algo AES256 sophon-snapshot-20260729-030412.zip
aws s3 cp sophon-snapshot-20260729-030412.zip.gpg s3://sophon-backups/

Backup archives are not encrypted by Sophon — always encrypt before moving them to shared or cloud storage.

Limits

• Backups are full snapshots of the data directory — there is no selective per-category export and no incremental mode today.
• One backup runs at a time, process-wide; concurrent creates return 409.
• Backups can run while the Gateway is live. Each file is hashed exactly as archived, but a backup taken under heavy write load is not a point-in-time transaction across files — schedule backups for quiet hours on busy instances.
• Large document libraries dominate archive size; budget disk in <data-dir>/backups/ accordingly.

Where to go next

• Compliance — DSAR exports, retention, archival
• Self-Hosting → Backup & Upgrade — operator runbooks
• CLI Command Reference — the backup & snapshot commands in context