Coven Documentation

Interactive reference for the Coven daemon HTTP API over same-user local IPC. Per-endpoint schemas, code samples, and Try It panels that target your local daemon.

The Coven daemon serves a small HTTP/1.1 API over same-user local IPC: a Unix domain socket on Unix-like hosts or an owner-only named pipe on Windows. This section is the per-endpoint interactive reference, generated from openapi/coven.daemon.v1.yaml. For the narrative reference (concepts, error model, versioning rules), see Coven local API.

Start a daemon

The Try It panels on each endpoint page target http://localhost:{port}/api/v1 — click the server URL above any panel to change the port variable (default 3000). On Unix-like hosts, requests are bridged through a Next.js route handler that dials $COVEN_HOME/coven.sock first and falls back to a loopback TCP listener on the chosen port (coven daemon serve --tcp 127.0.0.1:3000). The bridge does not dial Windows named pipes, and native Windows does not currently implement the optional TCP listener, so Try It is unavailable on native Windows. JSON responses are pretty-printed by the bridge.

coven daemon start
coven daemon status   # verify pid + socket

Sanity-check from the terminal

Without leaving the shell:

curl --unix-socket "$HOME/.coven/coven.sock" \
  http://localhost/api/v1/health | jq .

A healthy daemon returns { "ok": true, "apiVersion": "coven.daemon.v1", ... }.

Transport and trust model

Property	Value
Protocol	HTTP/1.1 over same-user local IPC
Default local endpoint	`~/.coven/coven.sock` on Unix-like hosts; daemon-reported owner-only named pipe on Windows
Optional TCP	Unix-like hosts only: loopback listener via `coven daemon serve --tcp 127.0.0.1:3000` (standard port `3000`)
Auth	Operating-system permissions on local IPC — no Bearer / JWT / API-key / cookie
Contract	`coven.daemon.v1` served under `/api/v1`

On Windows, the named pipe's owner ACL provides the equivalent operating-system permission boundary described as socket permissions in generated examples.

Anyone who can connect to the local endpoint can act as a client. Keep $COVEN_HOME and the endpoint private to the owning user. See Authentication and local access for the full hardening posture.

Client handshake

GET /api/v1/health — confirm apiVersion === "coven.daemon.v1".
GET /api/v1/capabilities — discover available adapters and action ids.
Use versioned /api/v1/* routes only.
Branch on error.code, not message text — see the error envelope and code table.

Additive fields are allowed inside v1; breaking changes require a new route-prefix version. See API compatibility rules.

Endpoint groups

Sessions

Launch, inspect, and control harness sessions (codex, claude, coven-code, copilot).

Events

Append-only event log for a single session. Crash-safe resume via afterSeq.

Actions

Control-plane action router. Only known action ids are accepted.

Code samples

Every endpoint includes Unix-domain-socket samples in curl, TypeScript, Python, and Rust. Each sample reads $COVEN_HOME with a ~/.coven fallback and pretty-prints the JSON response. These generated samples are Unix-specific; native Windows clients must use a named-pipe-capable HTTP transport.

API Reference