Upgrades & Rollback

Upgrades

Stop the service, swap the binary, start the service. The data/ directory is forward-compatible across point releases by design — schema migrations, when they happen, are documented in release notes. The zen CLI automates the swap:

zen app update

With no arguments, zen app update derives the GitHub-Release URL for your platform, downloads the latest, and verifies it against the release’s signed SHA256SUMS.jws — fail-closed by default. Pin a specific release with --version 3.0.0, or point at a corporate mirror with --url <url> --sha256 <hash> for an air-gapped network.

Flow YAML carries version: "1.0.0" for forward-compat; only the major version is checked at load time. A platform upgrade that bumps the major is flagged by the validator output before promotion, so you find these at staging time, not at production runtime.

Two rollback dimensions

The two are decoupled by design — you can roll back a config without touching the binary, or vice versa.

Binary rollback

zen app rollback

Reverts to the previous artifact. The data/ directory is unchanged, so a restart picks up the previous version’s behaviour. Use when an upgrade breaks something. ~2 minutes of downtime, no data loss.

Configuration rollback

When Git versioning is enabled, every connection / environment / flow change is committed automatically. There is no zen CLI revert verb — reverting is one call to the REST version-revert endpoint (or the MCP revert-entity tool):

curl -X POST http://localhost:5000/api/v1/live/versions/<entity-type>/<name>/revert \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"commitHash":"<ref>"}'

Use when a config change broke a flow. Zero downtime.

Putting it together

Symptom	Action	Downtime
New binary misbehaves	zen app rollback	~2 min
A flow/connection edit broke a pipeline	REST versions/.../revert (or MCP revert-entity)	none
Bad data state	Restore from backup	varies

Write and rehearse a runbook entry for “binary rollback” before go-live — it’s on the checklist.