---
title: Health, server proof and host reports
description: 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.
section: server-api
order: 80
audience: [builder, operator, agent]
sources: [packages/harness-server/openapi.yaml, packages/harness-server/src/auth.ts, packages/harness-server/src/server.ts, docs/evidence-bundle.md, docs/board.md]
features: [server-api.health, server-api.openapi-yaml, server-api.auth, server-api.gears, server-api.evidence, server-api.board]
---

The routes on this page are about the server and its host rather than one session.

## Health {#health}

`GET /v1/health` (`getHealth`) needs no token:

```bash
curl -s http://127.0.0.1:8790/v1/health
```

```json
{ "status": "ok", "version": "0.1.0", "sessions": 2, "maxSessions": 8 }
```

Python `client.health()`, TypeScript `client.health()`.

## The OpenAPI document {#openapi}

`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:

```bash
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 {#proof}

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.

```bash
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"
```

```python
client.prove_server()        # raises ServerProofError when the proof is wrong
```

```ts
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 {#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:

```json
{ "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](/docs/server-api/sessions.md)); 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](/docs/server-api/agents.md#model)).

Python `client.gears()`, TypeScript `client.listGears()` (`client.gears()` for the whole answer).

## Evidence bundle {#evidence}

`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 |

```bash
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 {#board}

`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](/docs/server-api.md#auth): authentication and the Host check
- [Clients](/docs/server-api/clients.md)
