---
title: Daemon API reference
description: Every route a daemon calls on Venom Cloud under /api/mesh/v1, with its authentication, request and response bodies, and errors.
section: mesh
order: 50
audience: [builder, operator, agent]
sources: [services/nodejs-cloud/app/api/mesh/v1, services/nodejs-cloud/lib/auth/daemon.ts, services/nodejs-cloud/contracts/mesh-v1.schema.json, services/nodejs-cloud/contracts/types.ts, services/nodejs-cloud/contracts/timing.json, docs/cloud-mesh.md, docs/public-mesh.md, services/go-orchestrator/internal/mesh]
features: [mesh.api-mesh-channel, mesh.api-mesh-comms, mesh.api-mesh-content, mesh.api-mesh-deregister, mesh.api-mesh-enroll, mesh.api-mesh-epochs, mesh.api-mesh-heartbeat, mesh.api-mesh-jobs, mesh.api-mesh-jwks, mesh.api-mesh-poll, mesh.api-mesh-registry, mesh.api-mesh-rotate, mesh.api-mesh-self, mesh.api-mesh-usage]
---

The daemon API is what venom's orchestrator calls in mesh mode (`services/go-orchestrator/internal/mesh`). You need it only to write another daemon, a simulator or a monitor. The JSON Schema is `services/nodejs-cloud/contracts/mesh-v1.schema.json`, the TypeScript types `contracts/types.ts`, and the timing constants `contracts/timing.json`; the Go daemon tests against all three.

## Routes {#routes}

| Route | Auth | Purpose |
|---|---|---|
| [`POST /api/mesh/v1/enroll`](#enroll) | join token in the body | register a daemon and its public key |
| [`POST /api/mesh/v1/heartbeat`](#heartbeat) | daemon JWT | renew the lease, report load and models |
| [`GET /api/mesh/v1/channel`](#channel) | daemon JWT | SSE stream of dispatches and control messages |
| [`GET /api/mesh/v1/poll`](#poll) | daemon JWT | long-poll fallback for the channel |
| [`POST /api/mesh/v1/jobs/{job_id}/ack`](#ack) | daemon JWT | claim a dispatched job |
| [`POST /api/mesh/v1/jobs/{job_id}/events`](#events) | daemon JWT | stream a relayed job's response back |
| [`POST /api/mesh/v1/usage`](#usage) | daemon JWT | report usage of direct (ticketed) requests |
| [`POST /api/mesh/v1/content`](#content) | daemon JWT | send a direct request's bodies when the org logs content |
| [`POST /api/mesh/v1/comms/inbound`](#comms-inbound) | daemon JWT | replies to the owner's own Telegram, from people it wrote to |
| [`POST /api/mesh/v1/rotate`](#rotate) | daemon JWT (old key) | replace the daemon's public key |
| [`POST /api/mesh/v1/deregister`](#deregister) | daemon JWT | leave gracefully |
| [`GET /api/mesh/v1/jwks`](#jwks) | none | the cloud's ticket-signing keys |
| [`GET /api/mesh/v1/epochs`](#epochs) | none | public mesh audit epochs and their revealed secrets |
| [`GET /api/mesh/v1/registry/{id}`](#registry) | daemon JWT | a public mesh registry entry and its golden set |
| [`GET /api/mesh/v1/self/qos`](#self-qos) | daemon JWT | the daemon's own claimed and witnessed QoS, trust and verdicts |

## Conventions {#conventions}

**Protocol header.** Requests and responses carry `venom-mesh-protocol: 1.<minor>` (the cloud sends `1.0`). A missing header is read as 1.x. A different major gets `426 daemon_upgrade_required` with `min_version`. Minors only add optional fields and message types; both sides ignore unknown fields and unknown message `type`s.

**Daemon JWT.** Every route marked so takes `Authorization: VenomMesh <jws>`, a compact JWS signed with the daemon's Ed25519 key:

| Header or claim | Value |
|---|---|
| `alg`, `kid` | `EdDSA`, the daemon id |
| `iss` | the daemon id |
| `aud` | the cloud origin, for example `https://cloud.usevenom.dev` (the cloud's `VENOM_CLOUD_ORIGIN` when set, else the origin the request used) |
| `iat`, `exp` | `exp − iat ≤ 60` seconds; ±30 s skew accepted |
| `htm`, `htu` | the HTTP method and the path without query |
| `bh` | on POST: base64url SHA-256 of the exact body bytes |

There is no replay store: heartbeats and event uploads are idempotent by `seq`, usage by `request_id`. Failures are `401 daemon_unauthorized` with the reason in the message; a revoked daemon gets `401 daemon_revoked` on every route and must stop.

**Errors** have the OpenAI shape with `type: "mesh_error"`: `{"error": {"message": "…", "type": "mesh_error", "code": "…", "param": null}}`. A body that is not a JSON object is `400 invalid_request`.

**Clocks.** `ack`, `events`, `heartbeat`, `usage` and `content` accept an optional `hlc` field and answer with the cloud's `hlc`, a hybrid logical clock stamp used to order a job's timeline across machines. It never affects leases or deadlines.

## POST /api/mesh/v1/enroll {#enroll}

No JWT: the join token authenticates. Body at most 1 MiB.

```json
{
  "join_token": "vjt_…",
  "public_key": "<base64url Ed25519 public key, 32 bytes>",
  "name": "gpu-sg-1",
  "version": "0.3.0",
  "protocol": "1.0",
  "hostname": "gpu-sg-1",
  "geo": {"lat": 1.29, "lon": 103.85, "country": "SG", "region": "ap-southeast-1"},
  "endpoints": [{"kind": "tailnet", "url": "http://100.101.102.103:8787/v1", "network": "acme.ts.net"}],
  "capabilities": {"models": [], "serve": false, "max_jobs": 16, "hardware": {"gpus": [{"name": "RTX 4090", "vram_gb": 24}], "ram_gb": 64}}
}
```

- `endpoints[].kind` is `public`, `tunnel`, `tailnet` or `lan`. Plain `http` only for `tailnet` and `lan`, which also need `network`.
- `geo` may be `{"region": "…", "source": "tz"}` when inferred from the time zone, or absent.
- `capabilities.models` is a list of `ModelCap`: `id`, `alias`, `context_window`, `vision`, `tools`, `responses`, `decisions`, `local`, `cloud_targets`, `max_inflight`, `price_in` and `price_out` (USD per million tokens, 0 for local models), optional `endpoints` (`["/v1/embeddings"]`, `["/v1/rerank"]` for models that serve only that), and for public models `registry_id` and `sampler`.

`201`:

```json
{
  "daemon_id": "…", "tenant_id": "…", "team_id": "…",
  "jwks_url": "/api/mesh/v1/jwks",
  "timing": {"heartbeat_ms": 10000, "lease_ms": 30000, "channel_ms": 270000, "poll_wait_s": 25, "ack_timeout_ms": 2000, "job_lease_ms": 30000}
}
```

| Status | `code` | When |
|---|---|---|
| 400 | `invalid_request` | bad `public_key`, missing `name`, a bad endpoint |
| 401 | `join_token_invalid` | malformed, unknown, revoked or used up |
| 403 | `daemon_barred` | the key was barred from the public mesh |
| 403 | `plan_limit_reached` | the org's plan allows no more daemons |
| 409 | `daemon_name_taken` | names are unique per tenant |
| 410 | `join_token_expired` | |
| 426 | `daemon_upgrade_required` | unsupported `protocol` major |

The token is spent in the same transaction.

## POST /api/mesh/v1/heartbeat {#heartbeat}

Every `next_heartbeat_ms`. Renews the daemon's lease and the leases of the jobs it lists.

```json
{
  "seq": 1042,
  "state": "active",
  "version": "0.3.0",
  "load": {"inflight": 3, "queued": 0, "slots": 8},
  "models_hash": "sha256:…",
  "models": null,
  "per_model": {"venom-default": {"ttft_p50_ms": 180, "ttft_p95_ms": 420, "inflight": 2, "errors_1m": 0, "requests_1m": 14}},
  "endpoints": null,
  "jobs": [{"job_id": "…", "attempt": 1, "state": "running", "last_seq": 88}],
  "rtt_ms": 212
}
```

- `seq` is required. `state` is `active` or `draining`.
- `models` (a `ModelCap` list), `capabilities` and `endpoints` are sent only when they changed (`models_hash` differs), else `null` or absent.
- `rtt_ms` is the previous heartbeat's round trip. `geo` comes with the first heartbeat after each start.
- Optional: `metrics` (host uptime, tokens per second, memory, GPUs, loaded models), `heal` (the daemon's self-heal state), `prewarm` (the result of a prewarm the cloud asked for) and `telegram_user` (the owner's own Telegram account on this daemon, see [comms/inbound](#comms-inbound)).

`200`:

```json
{
  "lease_expires_at": "…",
  "next_heartbeat_ms": 10000,
  "accept": {"tenant_id": "…", "teams": ["…"]},
  "cancel": ["<job_id>"],
  "config_version": 1,
  "jwks_kids": ["k2", "k1"],
  "hlc": "…"
}
```

`accept.teams` is the daemon's key group plus the key groups it is shared with (the protocol calls a key group a `team`); tickets for other key groups must be refused. `next_heartbeat_ms` is max(10 s, live daemons in the tenant ÷ 50 per second). `prewarm` (`{id, models, keep_alive_s?, reason?}`) asks the daemon to load models now; it repeats until a heartbeat reports a result with that id, or 10 minutes pass.

## GET /api/mesh/v1/channel {#channel}

An SSE stream from the cloud to the daemon. Each message is `event: <type>`, `id: <seq>`, `data: <json>`; `: ping` comes every 10 s. The cloud closes the stream at `channel_ms` (its function's maximum duration minus 30 s), sending `rotate` just before; the daemon opens the next channel 15 s earlier so they overlap, and the cloud de-duplicates by `job_id`. `Last-Event-ID` is accepted but not needed: an unacked dispatch is sent again.

| `type` | Fields | Daemon's action |
|---|---|---|
| `dispatch` | `job_id`, `attempt` (from 1), `created_at`, `deadline_at`, `tenant_id`, `key` `{id, name, team_id}`, `session?` `{id, parent?}`, `idempotency_key?`, `request` `{method, path, headers, body, stream}`, `routing` `{model, reason, hedge}`; public jobs add `provenance` `{nonce, registry_id, temp_milli, top_p_milli, top_k, max_tokens}` | ack within 2 s, then run the request through its own `/v1` handler |
| `cancel` | `job_id`, `attempt`, `reason` (`client_gone`, `hedge_lost`, `deadline`, `admin`) | stop the upstream; end with `ended: "client_gone"` unless the reason is `hedge_lost` |
| `config` | `config_version`, `timing?`, `accept?` | apply |
| `drain` | `reason` | stop claiming, finish running jobs |
| `rotate` | `reason: "channel_time"` | the stream is about to close |

`request.path` is one of `/v1/chat/completions`, `/v1/responses`, `/v1/completions`, `/v1/embeddings`, `/v1/rerank`, `/v1/systemone`. `request.headers` is an allowlist (`content-type`, `accept`, the `x-venom-*` session, cache, tier and priority headers, `openai-beta`, `x-stainless-retry-count`), never `Authorization`. `body` is the client's JSON, at most 4 MiB. A remote `venom serve` session arrives as a dispatch of kind `serve`, which the daemon forwards to `VENOM_MESH_SERVE_URL`.

## GET /api/mesh/v1/poll {#poll}

`?wait=<seconds>` (default and maximum 25). Returns `{"messages": [ … ]}`, the same message objects as the channel, as soon as there are any or after `wait` seconds.

## POST /api/mesh/v1/jobs/{job_id}/ack {#ack}

Body `{"attempt": 1}`. `200 {"state": "running", "job_lease_ms": 30000, "hlc": "…"}`; repeating an ack is harmless.

| Status | `code` | Meaning |
|---|---|---|
| 409 | `job_taken` | the ack deadline passed and the job went to another daemon or attempt; drop it |
| 410 | `job_gone` | the job was cancelled, or `job_id` is not a known UUID |

## POST /api/mesh/v1/jobs/{job_id}/events {#events}

The relayed response, in order, batched, each batch at most 1 MiB (`413 request_too_large` above that). The first `data` event after `head` goes at once; after that the Go daemon flushes every 20 ms or 16 KiB, with up to 4 POSTs in flight per job.

```json
{"attempt": 1, "events": [
  {"seq": 0, "type": "head", "status": 200, "headers": {"content-type": "text/event-stream", "x-venom-upstream": "ollama", "x-venom-model": "qwen3:8b"}},
  {"seq": 1, "type": "data", "data": "data: {\"choices\":[…]}\n\n"},
  {"seq": 57, "type": "end", "usage": {"tokens_in": 812, "tokens_out": 140, "cached_tokens": 640, "cost_usd": 0}, "ttft_ms": 190, "duration_ms": 4100}
]}
```

| Event | Fields |
|---|---|
| `head` | `status`, `headers` (`content-type`, `x-venom-*`, `retry-after`, `x-should-retry`); must be seq 0 |
| `data` | `data` (UTF-8 text) or `data_b64` (binary, standard base64), the exact response bytes |
| `receipt` | public jobs only, just before `end`: `receipt`, `output_ids` (see [Provenance and receipts](/docs/mesh/provenance.md#receipts)) |
| `end` | `usage`, `ttft_ms`, `duration_ms`, `ended?` (`client_gone` when cut short for a departed client, with the partial usage) |
| `error` | `phase` (`before_first_byte` or `mid_stream`), `status`, `code`, `message` (client-safe) |

`200 {"ack_seq": 57, "cancel": false, "hlc": "…"}`. `cancel: true` means the client left: stop the upstream and send one `end` with `ended: "client_gone"`. Duplicate `seq` values are ignored. `events` that is not an array is `400`; a stale attempt `409 job_taken`; an unknown job `410 job_gone`. An error before the first byte with status 429 or 5xx makes the cloud try the next daemon.

## POST /api/mesh/v1/usage {#usage}

Usage of direct requests the daemon served under a ticket, within 5 s of each finishing, at most 100 reports per call.

```json
{"reports": [{
  "jti": "…", "key_id": "<uuid>", "request_id": "req_…",
  "model": "venom-default", "upstream": "ollama", "served_model": "qwen3:8b",
  "status": 200, "tokens_in": 812, "tokens_out": 140, "cached_tokens": 640, "cost_usd": 0,
  "ttft_ms": 190, "duration_ms": 4100, "started_at": "…", "session": "s-123"
}]}
```

`200 {"accepted": <n>, "hlc": "…"}`. Reports are idempotent by `request_id`, and a report without a `request_id` or a UUID `key_id` is skipped. The cloud settles the ticket's budget reservation against it; a reservation with no report by the ticket's expiry plus 10 minutes is settled at its estimate, and a late report replaces the estimate. A finished background response (Responses API, `background: true`) is reported once more with `"settle": true` and its real tokens and cost (`job_id` instead of `jti` for a relayed one). `reports` that is not an array, or over 100, is `400`.

## POST /api/mesh/v1/content {#content}

Only for a direct request whose ticket had `content: true` (the key's org logs content). One report per call, at most 3 MiB (`413 request_too_large`).

```json
{"jti": "…", "key_id": "<uuid>", "request_id": "req_…",
 "request_b64": "…", "response_b64": "…", "request_bytes": 812, "response_bytes": 4096,
 "truncated": false, "ended": "client_gone"}
```

The daemon copies up to 1 MiB of each side as it streams (the client is always written first) and queues reports after the response ends. `200 {"stored": true|false, "hlc": "…"}`: `false` when the org no longer logs content. Idempotent by `request_id`; a copy replaces a stored one only when it saw more bytes. A bad `request_id` (not `req_…`) or `key_id` is `400`.

## POST /api/mesh/v1/rotate {#rotate}

Body `{"new_public_key": "<base64url Ed25519>"}`, signed with the current key. The swap is immediate; sign every later call with the new key. `200 {"ok": true}`; a bad key is `400 invalid_request`. `orchestrator mesh rotate` calls it.

## POST /api/mesh/v1/deregister {#deregister}

Body `{"reason": "shutdown"}` (kept, at most 200 characters). The daemon goes `offline` and its lease ends now. `200 {"ok": true}`. `orchestrator mesh leave` and a drained SIGTERM call it.

## GET /api/mesh/v1/jwks {#jwks}

Public, cacheable for 5 minutes. The keys the cloud signs tickets with:

```json
{"keys": [{"kty": "OKP", "crv": "Ed25519", "kid": "k2", "x": "…", "use": "sig", "alg": "EdDSA"}]}
```

A daemon caches it for an hour and refetches on an unknown `kid` (the heartbeat's `jwks_kids` lists the current ones). It verifies `vtk.` tickets offline against it: `aud` must be the daemon id, `tid` and `team` in the accept set, the model in `models`, and a request ticket's `jti` unused. The list is empty when the cloud has no `VENOM_MESH_SIGNING_KEYS`, and then every request is relayed.

## GET /api/mesh/v1/epochs {#epochs}

Public, no credentials. Query `from` and `to`: epoch numbers (unix ms ÷ 3,600,000) or ISO times; default the last 24 hours and the next epoch; at most 744 epochs apart (`400 invalid_request` otherwise).

```json
{"epoch_ms": 3600000, "data": [{"epoch": 498192, "starts_at": "…", "ends_at": "…", "secret_sha256": "…", "secret": "<base64url, only once ended>"}]}
```

How to use it to recompute audit selection is in [Provenance and receipts](/docs/mesh/provenance.md#epochs).

## GET /api/mesh/v1/registry/{id} {#registry}

Any enrolled daemon may read any entry, for its preflight:

```json
{"id": "qwen3-8b-awq@1", "model": "qwen3-8b", "quant": "awq", "engines": ["vllm>=0.11"],
 "weights_sha256": {"model.safetensors": "…"}, "tokenizer_sha256": "…", "template_sha256": "…",
 "golden": [{"path": "/v1/chat/completions", "request": {}, "nonce": "…", "temp_milli": 700, "top_p_milli": 950, "top_k": 64, "max_tokens": 16, "prompt_ids_sha256": "…", "output_ids": [1, 2]}]}
```

`golden` is `null` when the entry has none. `404 not_found` for an unknown id. Entries are managed by the cloud operator with `/api/admin/v1/registry`.

## GET /api/mesh/v1/self/qos {#self-qos}

A public daemon's own report:

```json
{
  "daemon_id": "…",
  "claimed": {"qwen3-8b": {"ttft_p50_ms": 180}},
  "witnessed": {"qwen3-8b": {"w_n": 412, "w_ttft_p50": 195, "w_ttft_p95": 610, "w_tps_p50": 41, "w_slo_rate": 0.99, "receipt_fail_n": 0, "max_good_inflight": 6, "ack_p50_ms": 40}},
  "divergence": {"qwen3-8b": {"ratio": 0.92, "flagged": false}},
  "trust": {"state": "probation", "since": "…", "witnessed_ok": 412, "receipt_failures": 0, "passed_audits": 9, "failed_audits": 0, "inconclusive_audits": 1, "disputed_audits": 0},
  "verdicts": [{"audit_id": "…", "job_id": "…", "registry_id": "qwen3-8b-awq@1", "epoch": "498192", "state": "…", "run": 1, "verdicts": [], "created_at": "…", "verdict_at": "…"}]
}
```

`claimed` is the last heartbeat's `per_model`, `witnessed` the cloud's figures over the last 15 minutes, `trust` is `null` for a private daemon (one of the org's own). `verdicts` holds the last 20 verdicts whose audit epoch has ended, with their checks and evidence but without the per-audit `stats`; it never says which jobs were canaries, and the daemon's sequential-evidence score is never included. The admin version, `GET /api/admin/v1/daemons/{id}/qos`, has all of it.

## POST /api/mesh/v1/comms/inbound {#comms-inbound}

Replies to the owner's own Telegram account, which the daemon logged in to with `venom-daemon telegram login`
([Telegram from your own account](/docs/comms/telegram-personal.md)). Only new private messages from people the daemon
wrote to, never a group or a channel, at most 100 per call:

```json
{"channel": "telegram_user", "events": [{"id": "5013377201:2219", "from": "@ana_k", "name": "@ana_k",
  "text": "Thanks! Thursday afternoon works for me.", "received_at": "…"}]}
```

`200 {"accepted": ["5013377201:2219"], "hlc": "…"}`. `from` is the address the daemon wrote to (`@username` or an
E.164 number). `id` (`<user id>:<message id>`) is the event id: a batch sent again is accepted again and applied once.
`404 telegram_user_not_linked` when no member linked this daemon's account; the daemon keeps the events and sends
them again later. Any `channel` but `telegram_user` is `400`.

The heartbeat's `telegram_user` is the account's status: `state` (`logged_out`, `connecting`, `logged_in`, `paused`,
`error`), `username`, today's `sends_today` and `first_contacts_today` against `first_contact_limit`,
`min_interval_s`, `paused_until`, `last_error` and `link_hash` (sha256 of the link code the login printed). It is
absent when the daemon has no session. Sends reach the daemon as relayed jobs on
`POST /v1/comms/telegram-user/messages`, pinned to it; `docs/cloud-mesh.md` §6.8 has the body and every refusal.

## Related

- [How the private mesh works](/docs/mesh/cloud-mesh.md): the paths these routes serve.
- [The public mesh](/docs/mesh/public-mesh.md): receipts, audits and trust.
- [Connect a daemon](/docs/mesh/connect-daemon.md).
