Backup and Recovery

What to Protect

Data	Location	Contains
Database	`~/.syncro/hub.db`	All records, trust scores, routing rules
Task content	`~/.syncro-data/tasks/`	Task descriptions and artifacts
Aliases	`~/.syncro-data/aliases.toml`	Human-readable task alias mappings
Config	`~/.syncro/config.toml`	Identity, store URL, server settings

Automatic Backup

The spl serve instance backs up the database on every startup, into a per-instance directory keyed by the instance DID:

~/.local/share/syncropel/backups/instance-<did-tail>/hub.db.bak

<did-tail> is the 24-hex tail of your instance DID. To find your directory:

curl -s localhost:9100/health | jq -r .instance_did
ls ~/.local/share/syncropel/backups/instance-<tail>/

The daily backup job writes timestamped hub.db.<YYYYMMDD-HHMMSS> copies into the same directory. (An instance running on an isolated SYNCROPEL_HOME before its identity is bootstrapped keys the directory as home-<hash>/ instead.)

The backup directory is OUTSIDE ~/.syncro/ — removing that directory does not affect the backups.

Manual Backup

# Create a timestamped backup (use your instance directory from above)
cp ~/.syncro/hub.db ~/.local/share/syncropel/backups/instance-<tail>/hub.db.$(date +%Y%m%d-%H%M%S)

# List available backups across all instance directories
ls -la ~/.local/share/syncropel/backups/*/

Recovery

# Stop the instance
spl stop

# Restore from backup
cp ~/.local/share/syncropel/backups/instance-<tail>/hub.db.bak ~/.syncro/hub.db

# Restart — trust and config rebuild automatically from records
spl serve

# Verify
spl status
spl task list
spl trust

Portable Backup — Publish the Instance

From v0.118, the recommended portable backup is a published repository snapshot of the whole instance:

spl repo publish <namespace>/<repo> --relocation

--relocation is shorthand for --visibility L3 --scope instance --no-listing --carry-tokens: it snapshots the instance as a verified, portable repository tree. To rebuild a working instance from it on any machine:

# Client-side restore (with the daemon stopped)
spl repo restore <dir-or-https-url>

# Or hydrate a fresh home at boot
spl serve --repo <locator>

The startup .bak file protects against local file loss; the published repository is the canonical portable recovery form — it travels between machines and verifies its own integrity on restore.

What Rebuilds on Startup

The engine reconstructs all derived state from the immutable record log:

Trust scores — replayed from outcome records
Engine config — replayed from configuration records
Thread state — derived from records (state = fold(records))

Prevention

Use separate ports for development (--port 9200) and production (port 9100)
Development instances use --memory for ephemeral storage
Task content files in ~/.syncro-data/ are independent of the database