Daemon lifecycle
Lifecycle reference for the Coven daemon: start, status, restart, stop, socket binding, ledger recovery, and live-session behavior.
2 min read
The daemon lifecycle is intentionally small: start it, inspect it, restart it after configuration changes, or stop it when you want the local Coven runtime down.
coven daemon start
coven daemon status
coven daemon restart
coven daemon stopstatus is the safest first command in scripts and support flows. It tells you whether the background process exists, which socket it owns, and which API contract it is serving.
Start
coven daemon start creates $COVEN_HOME if needed, opens the SQLite store, binds $COVEN_HOME/coven.sock, writes $COVEN_HOME/daemon.json, and begins serving /api/v1.
Startup should fail closed when:
$COVEN_HOMEcannot be created or opened.- The socket path is not writable by the current user.
- The SQLite ledger cannot be opened.
- Another live daemon already owns the socket.
If a stale socket is present after a crash, use Recovery and upgrades before deleting anything by hand.
Status
Use status before relying on daemon behavior:
coven daemon statusThe useful fields are:
| Field | Why it matters |
|---|---|
pid | Confirms the process that owns this daemon instance. |
socket | Confirms which $COVEN_HOME is active. |
apiVersion | Confirms client compatibility with coven.daemon.v1. |
uptime / startedAt | Helps distinguish a fresh restart from a stale process. |
When building a client, prefer the HTTP health handshake over scraping CLI status text.
Restart
restart is the normal way to apply daemon-level changes such as a new COVEN_HOME.
export COVEN_HOME="$HOME/.local/share/coven"
coven daemon restartRestart should drain the old listener, release the previous socket, reopen the store under the selected state directory, and serve the same /api/v1 contract again.
Stop
stop shuts down the background daemon. Live sessions should be treated conservatively: clients must not assume a stopped daemon means a harness completed its work. Reattach or inspect the session ledger after starting the daemon again.
Client behavior during lifecycle changes
Clients should handle these states explicitly:
- Socket connection refused: show a
coven daemon starthint. - Health route responds with another
apiVersion: ask the user to update Coven or the client. - Live input returns
session_not_live: switch to replay or attach guidance. - Runtime unavailable: retry after a short delay or ask the user to inspect daemon status.
Related
Last updated on