Coven local API
The supported HTTP contract over same-user local IPC.
11 min read
The daemon serves /api/v1 over same-user local IPC: $COVEN_HOME/coven.sock on Unix-like hosts or an owner-only named pipe selected by COVEN_HOME on Windows. Use the endpoint reported by health or coven daemon status; do not construct a Windows pipe name from the Unix convention.
Use the API from a same-user local client when the CLI does not fit your workflow. Start with the health response, branch on its advertised capabilities, and treat structured errors as product behavior. Capabilities advertise availability, not authorization.
These details describe the current versioned source contract. Older installed builds may omit newer optional capabilities; negotiate with the running daemon rather than treating this page as proof that an upgrade has reached it.
Supported flow
GET /api/v1/health— verify reachability and API compatibility.GET /api/v1/capabilities— discover available route families and action ids.POST /api/v1/sessions— launch a validated harness session.GET /api/v1/sessionsandGET /api/v1/sessions/{id}— inspect records.GET /api/v1/events— read ordered session events with a cursor.POST /api/v1/actions— request a validated control action with the action id in the top-level JSONactionfield.
Error envelope
The daemon rejects malformed requests, unknown sessions, non-live input, unsupported harnesses, and project-root violations with a structured error envelope:
{
"error": {
"code": "invalid_request",
"message": "cwd is outside the Coven project root"
}
}For a working directory outside the project root, the emitted code is invalid_request; project_root_violation is reserved, not the current wire code for that rejection. Do not depend on the message text as a stable subtype.
Use error.code for control flow; display message to people. The complete endpoint schemas and local examples are in the interactive API reference.
Session-policy admission
coven.session-policy.v1 is a separately negotiated contract for restricted launches. This version is refusal-only: no enforcement backend exists, so it never launches a session, issues a receipt, or grants a profile.
GET /api/v1/session-policyis inert discovery. It reports"enforcement": "unavailable"and an emptysupportedProfileslist.POST /api/v1/sessions/restrictedrequires local IPC; TCP returns403 forbidden. A valid request returns HTTP409with"decision": "rejected","code": "enforcement_unavailable", and"admission": "not_started". This closed refusal is not the generic error envelope, and it is never a launch success.- Health lists
coven.session-policy.v1insessionPolicyContractsover local IPC and returns[]over TCP. Older daemons omit the field; treat absence as unavailable. POST /api/v1/sessionsrejects any top-levelsessionPolicymember, includingnull, with400 invalid_request.
Never retry a restricted request as an ordinary launch, and do not infer not_started from a timeout, a disconnect, or a generic error. Other 409 responses are ordinary structured errors, such as session_policy_expired on the restricted route or session_not_live on session input, so the status alone does not identify a policy refusal. The closed request schema, size limits, and digest rules are in the session-policy specification.
A contract name in health establishes availability, not authorization. It is not an enforcement profile, identity proof, or grant.
Ordinary-chat context admission
Ordinary-chat context admission is not enabled. Owner-local POST /api/v1/sessions and POST /api/v1/sessions/{sessionId}/input validate an explicit contextAdmission intent and refuse execution while trusted embodiment verification and native context-profile qualification are absent. Valid unverified requests receive 503 with accepted: false and receiptIssued: false; other mutations reject the member rather than dispatching an unbound session. Requests without it keep their existing behavior.
Do not remove a refused contextAdmission member and retry as an ordinary launch or input. This intent is separate from session-policy admission, executionBinding, and requestAdoption; it advertises no new capability. See the ordinary-chat context contract.
Action router
The action router accepts a top-level action string plus optional origin and intentId correlation fields. Action-specific fields are also top-level; there is no generic args wrapper in the current daemon implementation. Correlation fields do not grant authority.
{
"action": "coven.automations.health",
"origin": "local-maintainer-tool",
"intentId": "inspect-daily-notes-1",
"id": "daily-notes"
}Call /capabilities before invoking an action. The currently advertised stable action groups include coven.capabilities.refresh and the coven.automations.* actions documented in Coven automations.
A successful action returns ok: true, accepted: true, and status: "completed", with its data in event.payload or, for versioned automation actions, a top-level result. A failed action returns ok: false, accepted: false, status: "rejected", and the cause in reason; versioned automation actions add a typed error whose code sets the HTTP status. Malformed JSON and missing action ids return HTTP 400. Over the optional loopback TCP listener, every coven.automations.* action outside the diagnostic allowlist returns 403 with AUTHORITY_REQUIRED before action validation, including unknown automation action ids. These actions require the owner-local IPC endpoint. Other unknown action ids return 400.
Control-plane surface map
The generated OpenAPI reference covers the stable public coven.daemon.v1 subset: handshake, capabilities, sessions, events, and actions. The daemon also exposes first-party route families used by OpenCoven applications. Those broader routes can evolve without a named-contract version bump and are intentionally not presented as public stable API.
Treat a route as stable only when it appears in the versioned source contract and the generated API Reference. For every other route, use capability discovery and the owning first-party client's contract instead of copying an implementation detail into an external integration.
Source builds also expose an owner-local internal mobile connection diagnostic for first-party clients. Its coarse observation never grants application authority and is outside this stable public subset.
Skills: eval-loop
coven eval-loop drives the held-out eval loop for a familiar's workspace. The CLI runs only the deterministic steps; the harness proposes changes and judges cases. Every subcommand takes --track (synthesis, prompt, or memory) and either --workspace <path> or --familiar <id>, resolved through ~/.coven/familiars.toml; --workspace wins when both are given.
coven eval-loop init --workspace . --track prompt # scaffold evals/<track>/{cases.jsonl,judge.md,config.json}
coven eval-loop noise start --workspace . --track prompt --runs 3 # plan repeated baseline scorings
coven eval-loop noise finalize --workspace . --track prompt # write noise.json and baseline.json
coven eval-loop begin --familiar sage --track prompt # start one iteration and take the run lock
coven eval-loop cases --familiar sage --track prompt --split train # print the cases for a split
coven eval-loop decide --familiar sage --track prompt # apply the accept rule and release the lock
coven eval-loop ack --familiar sage --track prompt # acknowledge the last iteration's trace
coven eval-loop status --familiar sage --track prompt # iteration history, noise, baseline, and lock stateEach command exits 0 on success, 3 when it refuses (with JSON { refused, detail }), and 1 on error.
init --test-pctsets the share of cases held out as the test split (default30).noise start --runs(default3) returns freshwrite_test_passes_toandwrite_train_topaths. Write the scores to those paths, then runnoise finalize.beginvalidates the track, checks headroom, noise, and baseline, takes the run lock, and writescontext.json.--from-run-jsonadopts a run the daemon enqueued instead of creating one, and--ack-unreviewedproceeds when the previous iteration's trace was not acknowledged. A refusedbeginis logged ineval-loop/skips.jsonland never counts as an iteration.cases --split testrequiresproposal.json. In a Git workspace, commit the proposal first: requesting the test split binds scoring to that commit and the evaluation inputs, anddeciderefuses a dirty or changed proposal.decideapplies the accept rule and a leak check, records a row inresults.tsv, and releases the lock. Ifnoise finalizeordecidefails while writing files, fix the filesystem error and rerun the same command; it resumes without counting an acceptance twice.- Calibration and iteration state fingerprint the split configuration and the judge rubric, so changing either requires recalibrating.
The daemon never drives the loop; it reads what the CLI writes. Its /api/v1/skills/eval-loop/:familiarId routes (read the state, enqueue a run, clear a stale run lock) belong to the first-party /skills/* family described in the control-plane surface map, outside the stable coven.daemon.v1 contract. Rows that decide writes report metricBefore, metricAfter, and delta on the held-out test split, along with the train-split metrics, the noise floor, and the eval-set hash.
Version and privacy rules
GET /api/v1/health advertises the named coven.daemon.v1 contract. Its covenVersion field is an opaque daemon build identity. Source builds may include a git describe distance, commit, or -dirty suffix; an unresolved version is unknown. Negotiate compatibility using apiVersion and the capabilities required for the operation. GET /api/v1/api-version is a legacy route-family diagnostic; its literal v1 value is not sufficient proof that every named-contract capability exists.
Broad event and log responses are redacted by default. Raw sensitive artifacts are available only through the narrow GET /api/v1/sessions/{sessionId}/artifacts/{artifactId}?raw=1 route when raw artifact persistence is explicitly enabled. Otherwise the daemon returns a structured raw_artifact_requires_raw_flag or raw_artifacts_disabled error.
Rust client and peer replacement
For Rust integrations, prefer opencoven-coven-client (library coven_client) to composing HTTP over a hand-built socket or pipe path. Construct the endpoint with DaemonEndpoint::discover(coven_home), then pass it to DaemonClient::new. The public client accepts no arbitrary URLs or endpoint paths, bounds response bodies to 4 MiB, and negotiates health before dependent operations. The crate lives in the OpenCoven/coven workspace; its crates.io release is gated on a signed coven-client-v* tag, so confirm a version is published before you add it as a registry dependency.
For a tighter total wait, the Rust client exposes DaemonEndpoint::discover_until and DaemonClient::request_json_until with an absolute deadline. Caller deadlines may shorten existing discovery/request maxima, never extend them. Negotiated health, owner/instance binding, structured errors and request limits remain enforced, and failures never trigger automatic replay. Filesystem metadata still depends on the host filesystem and scheduler.
Its negotiation is bound to the transport peer. If the daemon endpoint is replaced, the next dependent operation fails before sending request bytes and clears the cached negotiation. Call health again, re-check capabilities, and then decide whether a retry is appropriate. The client never replays a mutation automatically.
Client rules
- Send requests only to the daemon-reported same-user local IPC endpoint.
- Do not treat the optional loopback TCP listener as owner access; it refuses owner-only operations with
403. See Optional loopback TCP. - Check health and capabilities before assuming a route or action exists.
- Put action-specific fields at the top level and validate action payload results.
- Never treat a client-side check as a substitute for daemon validation.
- Keep provider credentials in the harness, not in API requests or automation definitions.
See Daemon for operating behavior, Safety for the enforcement model, and the versioned source contract for normative request and response shapes.
Main-session events and transcript
The first-party GET /api/v1/main-session response includes transcript.events and bytes for retained input/output payloads, plus the last reported harness context or null. Counts approximate transcript size: launch prompts are not stored as input events and retention may remove history. Claude's context uses the newest top-level model call's input and cache usage, excluding subagents. Context becomes unknown after compaction until a new model call; Codex plain-text output reports none. Reports are read from at most the newest 512 output events or 4 MiB. A reported window is not inferred when absent.
GET /api/v1/main-session/events streams retained events for the current conversation as UTF-8 SSE. Persist each complete frame's numeric id, then reconnect using Last-Event-ID to read larger sequence numbers. Cursors are global and may have gaps. A reset or rollover emits main_session.changed with an empty id, clears the reconnect cursor, and replays the replacement conversation; clear the displayed conversation on that event. An ordinary resume in the same conversation retains the cursor. Heartbeat comments arrive every 25 seconds and do not advance it.
The stream preserves owner-local permissions and the existing TCP Host/Origin and proxy checks; it adds no public access or mobile-gateway route. Capacity is 16 simultaneous streams. Events are bounded to 1 MiB and slow readers are disconnected under bounded write deadlines so they can replay their last complete frame. Before streaming, malformed cursors return 400 invalid_request, unavailable retained cursors return 409 event_cursor_unavailable, missing scopes return 404 main_session_not_found, and capacity exhaustion returns 503 stream_capacity. An oversized next event emits event_response_too_large and closes without advancing the id; surface the error rather than silently skipping the event. Retention still applies.
Main-session compaction
For Claude, an idle main-session host whose reported context reaches 60% of its reported window can receive a daemon-issued native /compact. The conversation and feed continue without rotation. Unknown windows do not trigger compaction. A failed attempt holds off another for 30 minutes; after success, another waits for context to grow by 10% of the window above the first post-compaction reading. Only one request remains open per conversation. A boundary followed by the first result settles it compacted; a result without a boundary, a stopped host, or a ten-minute timeout records failure. Crash reconciliation uses recorded evidence instead of sending a second open request.
lastCompaction records the request, settlement, trigger usage, reported pre/post sizes, and flush outcome. The corresponding main_session.compacted event contains a summary capped at 16 KiB and passed through the instance privacy policy. Durable facts established by the conversation's own messages, excluding system and instruction-file restatements, are appended to the familiar's memory/YYYY-MM-DD.md with a compaction marker for replay deduplication. There are at most 50 single-line facts of 1 KiB each. The write refuses symlink directories and notes, never truncates notes, and never writes the summary into MEMORY.md. A failed or empty daily-note flush is separate from compaction success.
Main-session notices
Daemon components can queue runtime notices per scope. Posting is daemon-internal; it is not a public client mutation route. Notices drain into the next turn or arrive as a separate turn when the bound stream process is known idle. Busy, absent, one-shot, starting, and unknown runtimes leave them pending. A notice is marked delivered only after its prompt reaches a process. Bodies are explicitly framed as untrusted daemon-component content, sanitized, and limited to 16 KiB; they are never presented as user or system instructions.
The generic inbox holds 20 pending notices per scope; a 21st can drop its oldest pending notice. A matching context_key replaces a pending notice, while delivered history remains. Automation result delivery instead defers while full, as described under Result delivery.
Hub job completion may supply a nonempty resultSummary of at most 8 KiB after trimming. The job's terminal state, notice, and delivery record commit together. A full inbox, invalid notice source id, or posting failure still completes the job but records delivery failed with a reason. Repeated completion keeps the first summary and notice. Job reads expose resultSummary and delivery, including whether the notice is pending, delivered, or dropped. Completion and delivery to a turn remain distinct outcomes.
Last updated on