Backups & Restore

Backups are first-class. The platform ships a scheduler, two tier presets, and a REST/MCP surface — there is no zen CLI backup verb. The defaults in appsettings.yaml cover the common case.

The two tiers

Tier	Contents	Schedule	Retention
Config	flows, environments, scripts, auth, secrets, annotations, folios, context, tasks	Daily 02:00	90 days, max 100 archives
Data	runs, persist state, shares, indexes, introspection	Weekly Sun 03:00	30 days, max 30 archives

The scheduler aborts a backup before it starts if free disk falls below MinFreeSpaceMb (500 MB default), and aborts in-flight if it falls below AbortOnLowSpaceMb (100 MB default).

Operations

# Ad-hoc backup of selected categories (generic entity surface)
curl -X POST http://localhost:5000/api/v1/platform/entities/backup \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"categories":["flows","environments","secrets"]}'

# List existing backups
curl http://localhost:5000/api/v1/platform/entities/backup -H "Authorization: Bearer $TOKEN"

# Restore a specific backup (bespoke verb)
curl -X POST http://localhost:5000/api/v1/platform/backups/<backup-id>/restore \
  -H "Authorization: Bearer $TOKEN"

The MCP equivalents are create-entity/list-entities (entity: backup) and restore-backup.

Restore semantics

A restore is additive by default: it merges the archive’s contents over current state. For a clean restore, stop the service, wipe the relevant buckets, restore, then restart.

Caution

Practice a restore on a non-production host before you need it. The “tested restore” checkbox in the pre-go-live checklist is the part that catches sites out.

Off-host copies

Backup archives live under {Backup.Storage.Directory} (default backups/). They are regeneratable — the next scheduled run produces a new archive — but only off-host copies survive a host-loss event. The backup of last resort is whatever ships your archives off the box: rsync to a backup server, S3 sync, or an external rotation policy in your storage tier.

Remember that secrets (auth/secrets.enc) are part of the config tier but, like git sync, must be handled carefully — losing the encryption key makes the encrypted blob useless. Back up the key alongside (but separately from) the blob.