Daemon
Overview of the Coven daemon: the local Rust process that owns session state, PTY lifecycle, the SQLite ledger, the event log, and the versioned socket API.
2 min read
The Coven daemon is one Rust process per host. It owns live session state, harness PTYs, the SQLite session ledger, the append-only event log, and the HTTP-over-Unix-socket API under /api/v1.
Clients such as the coven CLI, TUI surfaces, Cast Agent, and the OpenClaw bridge are user interfaces. They can validate requests for a better UX, but they do not become the enforcement boundary. They ask the daemon to launch sessions, forward input, kill live sessions, inspect events, or route control-plane actions.
For the visual route topology, compatibility handshake, event cursor flow, launch lifecycle, and daemon authority diagrams, see API architecture diagrams.
What the daemon owns
| Surface | Daemon responsibility |
|---|---|
| PTY lifecycle | Spawns supported harnesses with argv APIs, tracks live processes, forwards input, records exits. |
| Session ledger | Stores session records in SQLite so clients can list, attach, replay, archive, and diagnose work. |
| Event log | Appends output, input, status, exit, and action events with stable sequence cursors. |
| Socket API | Serves the local /api/v1 contract over <COVEN_HOME>/coven.sock. |
| Policy boundary | Canonicalizes project roots and cwd, validates harness ids, session ids, liveness, and action ids. |
Operational map
Start with these pages depending on what you are doing:
- Lifecycle for
start,status,restart,stop, and live-session behavior. - Configuration for
COVEN_HOME, socket paths, and on-disk state. - Socket API for health, capabilities, versioning, endpoints, and structured errors.
- Security posture for same-user socket trust, provider credential boundaries, and remote access.
- Observability for logs, diagnostics, and bug-report evidence.
- Recovery and upgrades for stale sockets, orphaned sessions, and safe upgrade flow.
Where daemon state lives
By default, Coven stores daemon state under ~/.coven.
| Path | Purpose |
|---|---|
$COVEN_HOME | Root state directory. Defaults to ~/.coven unless overridden. |
$COVEN_HOME/coven.sock | Unix socket the daemon binds for local clients. |
$COVEN_HOME/coven.sqlite3 | SQLite session ledger and append-only event log. |
$COVEN_HOME/daemon.json | Background daemon metadata such as pid, socket path, and start time. |
Treat $COVEN_HOME as sensitive local state. It contains prompts, harness output, session metadata, and operational traces.
Compatibility handshake
Every client should begin with the daemon health route:
GET /api/v1/healthThe response advertises apiVersion, Coven binary metadata, daemon metadata, and the capability shape clients should branch on before using sessions, events, actions, or live input.
Related
Last updated on