Health, server proof and host reports
Check venom serve's health, fetch its OpenAPI document, verify a server holds the token before sending it, and read the gears, evidence and board reports.
The routes on this page are about the server and its host rather than one session.
Health
GET /v1/health (getHealth) needs no token:
curl -s http://127.0.0.1:8790/v1/health{ "status": "ok", "version": "0.1.0", "sessions": 2, "maxSessions": 8 }Python client.health(), TypeScript client.health().
The OpenAPI document
GET /v1/openapi.yaml (getOpenApi) needs no token and returns the contract this server implements, OpenAPI 3.1. Generate a client from it, or validate requests against it:
curl -s http://127.0.0.1:8790/v1/openapi.yaml -o venom-serve.openapi.yamlThe package ships the same file as @venom/harness-server/openapi.yaml. Its rendered form is the API reference (/docs/api/harness-server).
Prove the server before sending the token
A client that connects to a configured URL can't tell venom serve from another program listening there, and its first authenticated request would hand that program the token. POST /v1/auth/proof (proveServer) lets the server prove it holds the token first, without the client sending it.
- Send a fresh random nonce, 16 or more bytes as lowercase hex (32 to 128 characters), with no
Authorizationheader. - The server answers
{proof, port}:proofis lowercase hex HMAC-SHA256, keyed with the token (UTF-8), of"venom-serve-proof-v1\n" + nonce + "\n" + port, whereportis the local port the request arrived on. - Compute the same with your token. Send nothing else unless it matches. For a loopback URL, also require
portto equal the URL's port: otherwise a fake server on one port could relay your nonce to a real one on another. Behind a TLS proxy the ports differ and TLS identifies the server, so check the HMAC over the returned port only.
NONCE=$(openssl rand -hex 16)
R=$(curl -s -X POST http://127.0.0.1:8790/v1/auth/proof -H 'content-type: application/json' -d "{\"nonce\":\"$NONCE\"}")
PORT=$(echo "$R" | jq -r .port)
EXPECTED=$(printf 'venom-serve-proof-v1\n%s\n%s' "$NONCE" "$PORT" | openssl dgst -sha256 -hmac "$VENOM_SERVER_TOKEN" -r | cut -d' ' -f1)
[ "$EXPECTED" = "$(echo "$R" | jq -r .proof)" ] && echo "server holds the token"client.prove_server() # raises ServerProofError when the proof is wrongawait client.proveServer(); // throws ServerProofErrorThe answer reveals nothing about the token. The VS Code extension and venom serve pair do this before every connection. A malformed nonce is 400.
Gears
GET /v1/gears (listGears) lists the gears the server's venom.yaml offers (the built-in ones plus your own), for an editor's gear switcher:
{ "gears": [
{ "name": "cheap", "n": 1, "description": "fast and low cost", "model": "qwen-fast", "thinking": "low", "available": true },
{ "name": "eco", "n": 2, "available": false }
], "cloudInference": true }cloudInference (added 2026-11) says the server takes a session's cloudInference (Create a session); an older server leaves it out and refuses the field. Venom Cloud reads it before it runs a gear on cloud keys on a daemon.
n is the gear's key (1 to 12) when bound; model is what the gear resolves to against the provider's model list, absent (and available: false) when the provider serves none of its candidates. A server embedded without gears answers an empty list. To move a session to a gear, post its model to POST /v1/sessions/{sessionId}/agents/1/model (Agents).
Python client.gears(), TypeScript client.listGears() (client.gears() for the whole answer).
Evidence bundle
GET /v1/evidence?root=<dir>&base=<ref> (getEvidence) returns the evidence bundle of a repository's change, the venom.evidence/v1 document venom evidence --json prints: changed files, tests added, the impacted-test plan, benchmarks, evals, invariants (pass, fail, n/a), screenshots and risk.
| Query | Default | What |
|---|---|---|
root |
required | A directory inside the server's roots, in a git repository whose top level is inside a root too (403 root_not_allowed) |
base |
HEAD (the uncommitted changes) |
The ref to compare with. A value starting with - or holding anything but ref characters is 400 |
curl -s "$S/v1/evidence?root=/home/me/work/app&base=origin/main" -H "Authorization: Bearer $TOKEN"Python client.evidence(root, base=None), TypeScript client.getEvidence(root, base?).
Board health
GET /v1/board (getBoard) is the agent factory's health report, what venom board health --json prints: open issues per status:* label (queue), in-progress claims and their age, claim-to-PR-to-merge times per issue and per worker, gate runs on this host with their pass rate and stages that passed only on retry, requeues, and the merge queue (gateQueue). It is computed on request from the gh CLI and this host's gate state, at most once a minute. When gh fails, forge.ok is false and the gate parts are still filled in. 404 board_off when the server started without a board (no GitHub origin remote).
Python client.board(), TypeScript client.getBoard().
Related pages
- Server API overview: authentication and the Host check
- Clients