Backups & Restore

Backups are first-class. The platform ships a scheduler, two tier presets, and a CLI surface. 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	invocations, 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
zen backup create --categories flows,environments,secrets

# List existing backups
zen backup list

# Restore a specific backup (interactive — prompts for category selection)
zen backup restore <backup-id>

The same actions are on REST (/api/v1/platform/backups) and MCP (create-backup, list-backups, 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.