Workers and jobs
"Workers" in Zephr means several different background mechanisms. What they share: each has a user-visible inspection path, and none of them run silently against data you cannot see. The hosted plane also runs internal workers — those are not user-controllable and are out of scope here.
The on-box daemon (zephrd)
The daemon is the local sidecar the CLI starts and composes with:
zephr daemon start
zephr health
zephr tools list # list the daemon's tool catalog (tier + pin)
zephr memory tree # render the scope lattice as a live tree
zephr continuity report # per-agent state + convergence scoreThe tools list, memory tree, and continuity report commands are read-only state
surfaces hosted by the daemon. When the daemon is unreachable these surfaces fail with exit 69 — see the
Daemon entry in the troubleshooting catalog.
Lifecycle hooks
Hooks are the capture surface that fires on client lifecycle events:
zephr hook # show the lifecycle hook capability matrix
zephr connect-hooks # lifecycle-hook installation surface (advisory)The real installer is zephr hook install --write. Hooks both consume and provide events;
they are the capture surface for client lifecycle events and the mechanism behind integration
capture.
Compute pods
Pods materialize a profile into an isolated, ephemeral compute environment (a Firecracker microVM with a devcontainer, per the compute-plane design) exposing profile MCP servers, LSP, lens indexers, and agents across MCP/ACP/exec surfaces. Pod commands run against the compute plane API for your account. The CLI verbs are exact:
zephr pod list
zephr pod show <pod-id>
zephr pod launch --template <id> [--profile <id>]
zephr pod pause <pod-id>
zephr pod resume <pod-id>
zephr pod terminate <pod-id>
zephr pod logs <pod-id>
zephr pod exec <pod-id> -- <command...>
zephr pod mcp <pod-id>
zephr pod acp <pod-id>
zephr pod egress-audit <pod-id>- Inspection is ungated:
list,show,logs, andegress-auditneed no capability consent. - Lifecycle is gated:
launch,pause,resume,terminate,exec,mcp, andacprequire capability consent — without it the CLI returns403 capability_denied. egress-auditlists the outbound hosts a pod attempted to reach, with the reason and time of each attempt — the pod's egress boundary, not a guess about it.zephr pod launchrequires a template id. Pod ids are tenant-scoped; a cross-tenant pod id returns the tenant-scoped not-found.devpodis a deprecated alias for pod commands, handled inside the CLI.
Honest status. The compute plane is evolving: the pod lifecycle contract and CLI surface ship, but end-to-end hosted execution depends on the compute plane being wired for your deployment. Do not treat a pod that cannot launch as a broken local feature — check whether the plane is available to your account first. See the Workers entry in the troubleshooting catalog.
Autonomous agents
Agents are definitions with enqueued runs:
zephr agent create --name <name> --model <alias>
zephr agent run <id>
zephr agent list
zephr agent logsagent run enqueues a run: the agent worker claims it and executes it on the cloud worker
plane — the CLI never executes agent runs in-process, and no API exists for direct, ungated
agent execution. Runs see only the tools granted by their scope, and agent-captured beliefs
are never self-confirmed — a human confirms through the review surface.
Honest status. The agent surface is evolving: agent definitions, the queue consumer,
and manual-trigger enqueue ship, but full governed execution is still hardening. Treat
agent run as "queued for the execution plane", then confirm via agent logs.
Sync reconciliation
zephr sync is the unified reconciliation loop over the canonical workspace snapshot: it
reapplies managed client state and reports per-client outcomes (synced, drifted,
conflict, not-installed). A run that only partially succeeds exits with code 5 (drift).
See the Sync entry in the troubleshooting catalog and
Monitoring for exit-code reading.
Review runs
zephr review runs an LLM-augmented governed review of a code change. A review is a job with
an explicit result: findings, or a structured abstention when the review substrate is
unavailable — a verdict is never fabricated. See
the Trust entry in the troubleshooting catalog.
Health of the whole set
Run zephr doctor after any change to how background work runs (daemon restarts, hook
installs, pod template changes). It checks the binary, the daemon socket, client handshakes,
and schema — see Monitoring.