FeaturesDiscussionsPreviewSkillsMobileOrchestrationDocs
Theme
Get Started
Sophon Docs
Administration

Backup & Export

Export chats, documents, memory, workflows, and configuration — for migration, archival, or data portability.

Sophon's backup + export system covers three use cases: routine backups for disaster recovery, one-off exports for migration, and compliance-driven data extraction for right-to-erasure and DSAR workflows.

This page focuses on the first two; compliance-driven extraction is covered under Compliance.

What's in a backup

A full backup bundles:

  • User records — hashed passwords, roles, tenant assignments, 2FA secrets
  • 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 + FTS index rebuild hints
  • Cron jobs — definitions + execution history
  • Webhooks — definitions (secrets redacted for security)
  • Connections — metadata (auth tokens not included — by design)
  • Channels — configuration (tokens redacted)
  • Skills — which are installed, enabled per agent, their versions
  • MCP config — mcp.json, mcp-server.json (tokens redacted)
  • Sophon Node — pairings (secrets redacted; re-pair on restore)
  • Discussions, Insights, Tasks, Approvals — history
  • Audit log — filterable; full log on Enterprise with compliance feature
  • License key — included or excluded per backup settings
  • Gateway config — appsettings.json + overrides

Secrets are always redacted from backups. This is deliberate — backups circulate, and a leaked backup shouldn't be a credential breach. On restore, you re-configure credentials and re-pair devices.

Creating a backup

Dashboard

Settings → Backup → Create. Choose:

  • Scope — everything, or select by category (chats, documents, memory, workflows, etc.)
  • Format — zip (default), tar.gz
  • Encryption — optional passphrase (AES-256 symmetric)
  • Destination — download, S3, Azure Blob, SFTP, local path

For large exports (GB+), prefer S3 / Azure Blob sinks — the Gateway streams directly without holding bytes in memory.

CLI

sophon backup create --out backup.zip
sophon backup create --categories memory,workflows,cron --out ops-backup.zip
sophon backup create --encrypt --passphrase-file ~/.backup-pass --out secure-backup.zip
sophon backup create --dest s3://sophon-backups/$(date +%Y-%m-%d).zip

Scheduled backups

Create a cron job that backs up automatically:

sophon cron add \
  --name nightly-backup \
  --schedule "0 3 * * *" \
  --action custom --command "sophon backup create --dest s3://sophon-backups/$(date +%Y-%m-%d).zip --encrypt"

Default nightly schedule — 03:00 server time. Retention: keep 7 daily + 4 weekly + 12 monthly by default.

Backup structure

A zip backup unpacks to:

backup/
├── metadata.json                 # Sophon version, tier, timestamp, tenant scope
├── manifest.json                 # Inventory of included files + checksums
├── users/
│   ├── users.json
│   └── 2fa-secrets.json.enc      # encrypted block
├── agents/
│   └── <agent-id>/
│       ├── SOUL.md
│       ├── BOOT.md
│       └── config.json
├── workflows/
│   └── <workflow-id>.json
├── memory/
│   ├── entries.jsonl
│   └── daily-logs/
│       └── YYYY-MM-DD.jsonl
├── documents/
│   ├── index.json
│   └── files/
│       └── <doc-id>.<ext>
├── cron/
│   └── jobs.json
├── webhooks/
│   └── webhooks.json             # secrets redacted
├── connections/
│   └── connections.json          # auth tokens redacted
├── skills/
│   └── installed.json
├── audit/
│   └── entries.jsonl             # if included
└── config/
    └── appsettings.backup.json   # secrets redacted

Restoring a backup

Full restore

sophon backup restore --in backup.zip

Restore is additive by default — existing entries are preserved; conflicts go to a quarantine folder for review. To restore into a fresh Gateway:

sophon backup restore --in backup.zip --mode replace

Replace mode wipes existing tenant-scoped data first. Double-confirm before running.

Selective restore

Restore specific categories:

sophon backup restore --in backup.zip --only memory,workflows

Useful when you want to recover a specific resource type without disrupting everything else.

Into a specific tenant

Multi-tenant deployments can target the restore:

sophon backup restore --in backup.zip --into-tenant acme

Dry run

Preview what a restore would change:

sophon backup restore --in backup.zip --dry-run

Output:

Would restore:
  users:        42 (3 conflicts — would go to quarantine)
  agents:       5
  workflows:    12
  memory:       8,471 entries (0 conflicts)
  documents:    189 files, 2.1 GB
  ...
Total size: 4.3 GB

Migration pattern

Moving from one Sophon instance to another:

  1. Source Gateway: sophon backup create --out migrate.zip --encrypt
  2. Transfer the file securely.
  3. Destination Gateway: fresh install, register admin user.
  4. Destination: sophon backup restore --in migrate.zip --mode replace
  5. Re-authenticate each connection (credentials were redacted).
  6. Re-pair each Sophon Node.
  7. Rotate any API tokens users care about.

Test on a small subset first if possible.

Incremental backups (Pro / Enterprise)

Instead of full backups, incremental backups capture only changes since the last backup:

sophon backup create --incremental --since-last --out incr.zip

Incremental backups reference a full backup by ID. Restoring requires the full + all incrementals after it (handled automatically).

Storage savings are substantial for large deployments — documents and audit log dominate backup size, and those grow slowly relative to churn in memory / sessions.

Encryption

Passphrase-encrypted backups use AES-256-GCM with a key derived via PBKDF2 (600,000 iterations). The passphrase is never stored alongside the backup — if you lose it, the backup is unrecoverable.

For automated backups, store the passphrase in a secure secret manager (AWS Secrets Manager, HashiCorp Vault, CI secret) and pass via --passphrase-file or SOPHON_BACKUP_PASSPHRASE env var.

Verification

Verify a backup without restoring:

sophon backup verify --in backup.zip

Checks:

  • All files listed in manifest are present
  • All checksums match
  • Metadata is well-formed
  • Sophon version compatibility
  • (If encrypted) passphrase is correct

Run this before trusting a backup in a DR drill.

Retention of backups

Backup files are your responsibility — Sophon writes them where you point (local path / S3 / Azure Blob / SFTP) but doesn't manage lifecycle. Use your storage provider's lifecycle policies (S3 lifecycle rules, Azure Blob retention) to age out old backups.

For Enterprise customers, Sophon's archive storage can double as backup retention:

{
  "Sophon": {
    "Backups": {
      "Default": {
        "Destination": "archive",
        "Lifecycle": {
          "KeepDaily": 7,
          "KeepWeekly": 4,
          "KeepMonthly": 12,
          "KeepYearly": 7
        }
      }
    }
  }
}

Limits

  • Max backup size: uncapped, but practical limits apply (32-bit zip max is 4 GB — use .tar.gz for larger backups).
  • Encrypted backups add ~1% overhead.
  • Scheduled backups run at server priority; avoid scheduling during expected peak traffic.
  • Dry-run on very large backups can take minutes.

Where to go next

Remote Access Onboarding

Generate short-lived onboarding tickets for operator-managed remote device enrollment.

Operations & System Health

Monitor Gateway health, manage services, view resource usage, control agent processing, and diagnose issues.

On this page

What's in a backupCreating a backupDashboardCLIScheduled backupsBackup structureRestoring a backupFull restoreSelective restoreInto a specific tenantDry runMigration patternIncremental backups (Pro / Enterprise)EncryptionVerificationRetention of backupsLimitsWhere to go next