Skip to content
Docs menu

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.

View .md

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.yaml

The 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.

  1. Send a fresh random nonce, 16 or more bytes as lowercase hex (32 to 128 characters), with no Authorization header.
  2. The server answers {proof, port}: proof is lowercase hex HMAC-SHA256, keyed with the token (UTF-8), of "venom-serve-proof-v1\n" + nonce + "\n" + port, where port is the local port the request arrived on.
  3. Compute the same with your token. Send nothing else unless it matches. For a loopback URL, also require port to 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 wrong
await client.proveServer();  // throws ServerProofError

The 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().