Zephr Docs

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 uninstall preserves 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-mcp server process, the SQLite store, the on-box daemon (zephrd), and the optional ugrep / typescript-language-server binaries. 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 MCP zephr_status report.
  • 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.

PurposeSafe command(s)
Installation healthzephr health, zephr doctor, zephr status
Daemon lifecyclezephr daemon start, zephr upgrade --check (release check — never downloads)
Recall sanityzephr recall <query>, zephr observations --ids <id,id,...>
Evidence integrityzephr verify --claim-id <id>, zephr why --claim-id <id>, zephr preflight --plan <plan.json>
Backup and continuityzephr pack <worktreeId> <outputPath>, zephr handoff <worktreeId> --file <path>, zephr receipts export --out <path>, zephr prove <packet.json>
Import and restorezephr pack import <file> --trust-signer <sha256:fingerprint>, zephr resume <claim-code|packet-id|file-path>
Usage and spendzephr usage review
Removalzephr 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.