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.
- The MCP client environment block — the
envmap 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. ZEPHR_*environment variables — read by the server, the CLI, and the daemon. The most important isZEPHR_DB_PATH; the full user-facing set is below.- Files under
~/.zephr— local CLI state:credentials.json(0600) holds authentication state andconfig.jsonholds the active role. The directory is overridable withZEPHR_CONFIG_DIR. - Activation workspace settings — a closed
activation.*allowlist read and written throughzephr activate config(below), stored server-side, not in a local file. - Launcher state — project, repository, and binding records created by the
zephr connectflow 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_PATHto an absolute filesystem path in the client'senvblock, or to:memory:for a throwaway session. - A plain server process with
ZEPHR_DB_PATHunset 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.dbwhere the data dir is$XDG_DATA_HOME/zephr(or~/.local/share/zephr), created with mode 0700. The database file (and its-wal/-shmsiblings) 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
| Variable | Purpose |
|---|---|
ZEPHR_DB_PATH | SQLite store path (:memory:, absolute, or relative to the server's working directory); trusted commands default to the platform data directory when unset |
ZEPHR_ADMIN_TOKEN | Operator-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_TOKEN | Optional, distinct token for local human review actions (must differ from the admin token) |
ZEPHR_REVIEW_PRINCIPAL | Optional stable reviewer label seed (8–128 bytes) |
ZEPHR_KEY_DIR | Installation key directory (default <data dir>/keys) |
ZEPHR_ACTOR_ID | Stable local user label recorded in registry events (default local-cli-user) |
ZEPHR_CONFIG_DIR | Overrides ~/.zephr for CLI state (credentials.json, config.json) |
ZEPHR_API_URL | API base URL for account-connected CLI commands |
ZEPHR_ROLE | Active role; overridden by the --role flag |
ZEPHR_DEVICE_CLIENT_ID | OAuth client id for the device flow |
ZEPHR_MCP_BIN | Absolute path to the on-box zephr-mcp binary |
ZEPHR_DAEMON_BIN | Absolute path to the zephrd daemon binary |
ZEPHR_DAEMON_SOCKET | Override 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_TOKENthemselves 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_unavailableeven 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 resetKeys: 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 --forcere-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.