Operations
This section is for operators — anyone who runs, monitors, backs up, or repairs a Zephr installation. Every page here restricts itself to procedures that are safe and user-controlled: commands you run against your own installation or account, with no access to private infrastructure.
The operating contract
- Your data stays where you put it. In local mode the store is a single SQLite file at the path you configure. It is not encrypted by Zephr at rest; place it on an encrypted volume if you need that.
- Read before you delete. Destructive operations are capability-gated: memory deletion
tombstones, file erasure is a governed path, and
zephr uninstallpreserves SQLite backups. - No silent guesses. Health and recall surfaces report honest states (
not_evaluated, abstention,degraded) rather than fabricating numbers or results. - Check statuses. A feature marked planned or evolving here is not claimed as shipped. Status truth lives in the capability map, never in marketing prose.
Where the boundary is
- On your machine — the
zephr-mcpserver process, the SQLite store, the on-box daemon (zephrd), and the optionalugrep/typescript-language-serverbinaries. Local mode makes zero network calls attributable to Zephr as part of normal operation, and capture is always an explicit tool call. - Your account's hosted plane — hosted tools, hosted library docs, sync, and fleet
surfaces. These fail closed (
not_wired,degraded,connect_ref) when not reachable or not wired — never half-working.
Pages
- Configuration — where Zephr reads configuration from:
the client environment block,
ZEPHR_*variables, local CLI state, and the activation settings allowlist. - Workers and jobs — background work you control: the daemon, lifecycle hooks, compute pods, autonomous agents, and sync reconciliation.
- Monitoring — the health surfaces:
zephr status,zephr health,zephr doctor, and the MCPzephr_statusreport. - Data lifecycle — retention, verified snapshots, portable exports, restore, deletion, schema-migration safety, and crash recovery.
- Troubleshooting — one symptom → diagnosis → safe command → expected output → recovery → escalation catalog across every major surface.
Quick command reference
All command names below are the exact names from the
generated CLI reference. Run zephr <command> on
the on-box CLI. Client launch and worktree admission go through the connect flow
(zephr connect — see Connect your client); there is no
separate launcher command surface to invoke by hand.
| Purpose | Safe command(s) |
|---|---|
| Installation health | zephr health, zephr doctor, zephr status |
| Daemon lifecycle | zephr daemon start, zephr upgrade --check (release check — never downloads) |
| Recall sanity | zephr recall <query>, zephr observations --ids <id,id,...> |
| Evidence integrity | zephr verify --claim-id <id>, zephr why --claim-id <id>, zephr preflight --plan <plan.json> |
| Backup and continuity | zephr pack <worktreeId> <outputPath>, zephr handoff <worktreeId> --file <path>, zephr receipts export --out <path>, zephr prove <packet.json> |
| Import and restore | zephr pack import <file> --trust-signer <sha256:fingerprint>, zephr resume <claim-code|packet-id|file-path> |
| Usage and spend | zephr usage review |
| Removal | zephr uninstall (dry run by default; preserves SQLite backups) |
When something breaks
Start in Troubleshooting. Every entry follows the same shape — symptom, diagnosis, a safe command, expected output, recovery, and when to escalate — and each command is drawn from the generated reference above. Nothing in this section requires access to infrastructure you do not control.