Zephr Docs

Configuration

A Zephr installation is configured from four places. Understanding which surface owns a setting is the whole game — there is no single config file that overrides the others.

  1. The MCP client environment block — the env map in your client's MCP server configuration. This is the primary source for server configuration because the client launches the server process with those variables.
  2. ZEPHR_* environment variables — read by the server, the CLI, and the daemon. The most important is ZEPHR_DB_PATH; the full user-facing set is below.
  3. Files under ~/.zephr — local CLI state: credentials.json (0600) holds authentication state and config.json holds the active role. The directory is overridable with ZEPHR_CONFIG_DIR.
  4. Activation workspace settings — a closed activation.* allowlist read and written through zephr activate config (below), stored server-side, not in a local file.
  5. Launcher state — project, repository, and binding records created by the zephr connect flow and stored in the store, not in a file. Rebind or detach with the connect flow's re-enrollment path (zephr connect --force) — never by editing a file.

ZEPHR_DB_PATH — where the store lives

The store is a single SQLite file. ZEPHR_DB_PATH accepts :memory:, an absolute path, or a path relative to the server process's working directory — and that last one is the trap: the working directory of a client-launched server is not under your control, so a relative path silently lands somewhere you do not expect.

  • For a client-launched server, set ZEPHR_DB_PATH to an absolute filesystem path in the client's env block, or to :memory: for a throwaway session.
  • A plain server process with ZEPHR_DB_PATH unset falls back to an in-memory store — fine for a smoke test, discarded when the process exits.
  • The trusted launcher instead falls back to the platform data directory: <data dir>/zephr.db where the data dir is $XDG_DATA_HOME/zephr (or ~/.local/share/zephr), created with mode 0700. The database file (and its -wal/-shm siblings) is restricted to mode 0600.
  • If your data "disappears after exit", check which path the process actually used — see the Privacy and deletion entry in the troubleshooting catalog.

User-facing ZEPHR_* variables

VariablePurpose
ZEPHR_DB_PATHSQLite store path (:memory:, absolute, or relative to the server's working directory); trusted commands default to the platform data directory when unset
ZEPHR_ADMIN_TOKENOperator-set token that gates the zephr_admin MCP tool's capability check (see below); verified in constant time; when unset, every admin action fails closed with capability_required
ZEPHR_REVIEW_TOKENOptional, distinct token for local human review actions (must differ from the admin token)
ZEPHR_REVIEW_PRINCIPALOptional stable reviewer label seed (8–128 bytes)
ZEPHR_KEY_DIRInstallation key directory (default <data dir>/keys)
ZEPHR_ACTOR_IDStable local user label recorded in registry events (default local-cli-user)
ZEPHR_CONFIG_DIROverrides ~/.zephr for CLI state (credentials.json, config.json)
ZEPHR_API_URLAPI base URL for account-connected CLI commands
ZEPHR_ROLEActive role; overridden by the --role flag
ZEPHR_DEVICE_CLIENT_IDOAuth client id for the device flow
ZEPHR_MCP_BINAbsolute path to the on-box zephr-mcp binary
ZEPHR_DAEMON_BINAbsolute path to the zephrd daemon binary
ZEPHR_DAEMON_SOCKETOverride the daemon Unix socket path (special value disabled is ignored)
ZEPHR_TEST_MODE"1" enables test mode for CI-style runs

Binary resolution follows the generic pattern: ZEPHR_<BIN>_BIN overrides the resolved path for a composed binary (binary name uppercased, non-alphanumerics as underscores), so ZEPHR_MCP_BIN and ZEPHR_DAEMON_BIN are the concrete cases of one rule.

zephr_admin is an MCP tool, not a CLI

The public zephr CLI has no zephr_admin command. The zephr_admin MCP tool (tier review, residency deferred) carries capability-gated administrative actions such as purge, migrate, and stats.

  • The operator sets ZEPHR_ADMIN_TOKEN themselves in the server's environment when the installation needs admin capability. It is not minted or distributed by Zephr.
  • A valid token is necessary but not sufficient: every admin action also requires a trusted user-presence attestation. Local stdio installations do not bind a presence surface, so they fail closed with presence_attestation_unavailable even when the token is set.
  • Purge and migrate are MCP tool actions only; this public guide does not expose their confirmation internals.

zephr activate config

Project-grounded activation reads and writes a closed allowlist of activation.* workspace-settings keys:

zephr activate config get <key>
zephr activate config set <key>=<value>
zephr activate config reset

Keys: activation.maxTools (default 2), activation.maxSkills (default 1), activation.budgetTokens (default 50000), activation.defaultRiskReview (default high). Validation is closed: tool/skill counts must be integers 1–16, budgetTokens ≥ 0, and defaultRiskReview one of low | medium | high | critical. reset restores all platform defaults. Reads are member+; writes are admin-gated server-side, and the CLI fast-fails locally when the persisted role cannot write. zephr activate plan / explain are read-only/dry-run (they never load tools or write config).

Precedence rules

  • The client environment block wins for anything the server process reads from its environment, because that is the environment the process is launched with.
  • activation.* settings live in the workspace settings surface, not the process environment — role gating applies to writes.
  • Launcher state is stored in the store, not configured — change it through the connect flow (zephr connect --force re-enrolls and rebinds).
  • Local CLI state files (~/.zephr) are per-machine; they do not configure the server.

If a configuration change does not take effect, confirm which surface it belongs to first: process environment, activation settings, local CLI state, or launcher state.