Daemon lifecycle
Lifecycle reference for the Coven daemon: start, status, restart, stop, local IPC binding, ledger recovery, and live-session behavior.
3 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 local IPC endpoint it owns, and
which API contract it is serving.
Start
coven daemon start creates $COVEN_HOME if needed, opens the SQLite store,
binds the platform local IPC endpoint ($COVEN_HOME/coven.sock on Unix-like
hosts or an owner-only named pipe on Windows), writes
$COVEN_HOME/daemon.json, and begins serving /api/v1.
Startup should fail closed when:
$COVEN_HOMEcannot be created or opened.- The local IPC endpoint cannot be created for the current user.
- The SQLite ledger cannot be opened.
- Another live daemon already owns the local IPC endpoint.
If local IPC metadata is stale 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 | Legacy field name containing the active Unix socket or Windows named-pipe endpoint. |
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 local IPC endpoint,
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.
Running under a service manager
Coven ships supervision recipes in the main repo, and their names are the convention to follow:
| Platform | Unit / label | Source |
|---|---|---|
| macOS (launchd) | Label coven, plist at ~/Library/LaunchAgents/coven.plist, running coven daemon start. | docs/install/launchd.md in the Coven repo. |
| Linux (systemd) | Unit coven-daemon.service, installed at /etc/systemd/system/coven-daemon.service, running coven daemon serve in the foreground under a dedicated coven user with COVEN_HOME=/var/lib/coven. | docs/daemon/coven-daemon.service in the Coven repo. |
macOS convention note: launchd labels are conventionally reverse-DNS (which for this project would look like com.opencoven.coven-daemon), but the shipped guide deliberately uses the short label coven — use that label in launchctl commands (launchctl kickstart -k gui/UID/coven, launchctl bootout gui/UID/coven) unless you have renamed the plist yourself.
Whichever supervisor you use, keep single-instance discipline: the daemon
refuses to take over a healthy local IPC endpoint and holds a serve lock, so
let one supervisor own the process rather than mixing coven daemon start
with a service unit.
Client behavior during lifecycle changes
Clients should handle these states explicitly:
- Local IPC 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.