CovenDocs

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

  1. GET /api/v1/health — verify reachability and API compatibility.
  2. GET /api/v1/capabilities — discover available route families and action ids.
  3. POST /api/v1/sessions — launch a validated harness session.
  4. GET /api/v1/sessions and GET /api/v1/sessions/{id} — inspect records.
  5. GET /api/v1/events — read ordered session events with a cursor.
  6. POST /api/v1/actions — request a validated control action with the action id in the top-level JSON action field.

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-policy is inert discovery. It reports "enforcement": "unavailable" and an empty supportedProfiles list.
  • POST /api/v1/sessions/restricted requires local IPC; TCP returns 403 forbidden. A valid request returns HTTP 409 with "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.v1 in sessionPolicyContracts over local IPC and returns [] over TCP. Older daemons omit the field; treat absence as unavailable.
  • POST /api/v1/sessions rejects any top-level sessionPolicy member, including null, with 400 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 state

Each command exits 0 on success, 3 when it refuses (with JSON { refused, detail }), and 1 on error.

  • init --test-pct sets the share of cases held out as the test split (default 30).
  • noise start --runs (default 3) returns fresh write_test_passes_to and write_train_to paths. Write the scores to those paths, then run noise finalize.
  • begin validates the track, checks headroom, noise, and baseline, takes the run lock, and writes context.json. --from-run-json adopts a run the daemon enqueued instead of creating one, and --ack-unreviewed proceeds when the previous iteration's trace was not acknowledged. A refused begin is logged in eval-loop/skips.jsonl and never counts as an iteration.
  • cases --split test requires proposal.json. In a Git workspace, commit the proposal first: requesting the test split binds scoring to that commit and the evaluation inputs, and decide refuses a dirty or changed proposal.
  • decide applies the accept rule and a leak check, records a row in results.tsv, and releases the lock. If noise finalize or decide fails 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.

Was this page helpful?No

Last updated on

On this page