Daemon API reference
Every route a daemon calls on Venom Cloud under /api/mesh/v1, with its authentication, request and response bodies, and errors.
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
| Route | Auth | Purpose |
|---|---|---|
POST /api/mesh/v1/enroll |
join token in the body | register a daemon and its public key |
POST /api/mesh/v1/heartbeat |
daemon JWT | renew the lease, report load and models |
GET /api/mesh/v1/channel |
daemon JWT | SSE stream of dispatches and control messages |
GET /api/mesh/v1/poll |
daemon JWT | long-poll fallback for the channel |
POST /api/mesh/v1/jobs/{job_id}/ack |
daemon JWT | claim a dispatched job |
POST /api/mesh/v1/jobs/{job_id}/events |
daemon JWT | stream a relayed job's response back |
POST /api/mesh/v1/usage |
daemon JWT | report usage of direct (ticketed) requests |
POST /api/mesh/v1/content |
daemon JWT | send a direct request's bodies when the org logs content |
POST /api/mesh/v1/comms/inbound |
daemon JWT | replies to the owner's own Telegram, from people it wrote to |
POST /api/mesh/v1/rotate |
daemon JWT (old key) | replace the daemon's public key |
POST /api/mesh/v1/deregister |
daemon JWT | leave gracefully |
GET /api/mesh/v1/jwks |
none | the cloud's ticket-signing keys |
GET /api/mesh/v1/epochs |
none | public mesh audit epochs and their revealed secrets |
GET /api/mesh/v1/registry/{id} |
daemon JWT | a public mesh registry entry and its golden set |
GET /api/mesh/v1/self/qos |
daemon JWT | the daemon's own claimed and witnessed QoS, trust and verdicts |
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 types.
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
No JWT: the join token authenticates. Body at most 1 MiB.
{
"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[].kindispublic,tunnel,tailnetorlan. Plainhttponly fortailnetandlan, which also neednetwork.geomay be{"region": "…", "source": "tz"}when inferred from the time zone, or absent.capabilities.modelsis a list ofModelCap:id,alias,context_window,vision,tools,responses,decisions,local,cloud_targets,max_inflight,price_inandprice_out(USD per million tokens, 0 for local models), optionalendpoints(["/v1/embeddings"],["/v1/rerank"]for models that serve only that), and for public modelsregistry_idandsampler.
201:
{
"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
Every next_heartbeat_ms. Renews the daemon's lease and the leases of the jobs it lists.
{
"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
}seqis required.stateisactiveordraining.models(aModelCaplist),capabilitiesandendpointsare sent only when they changed (models_hashdiffers), elsenullor absent.rtt_msis the previous heartbeat's round trip.geocomes 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) andtelegram_user(the owner's own Telegram account on this daemon, see comms/inbound).
200:
{
"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
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
?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
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
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.
{"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) |
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 of direct requests the daemon served under a ticket, within 5 s of each finishing, at most 100 reports per call.
{"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
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).
{"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
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
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
Public, cacheable for 5 minutes. The keys the cloud signs tickets with:
{"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
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).
{"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.
GET /api/mesh/v1/registry/{id}
Any enrolled daemon may read any entry, for its preflight:
{"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
A public daemon's own report:
{
"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
Replies to the owner's own Telegram account, which the daemon logged in to with venom-daemon telegram login
(Telegram from your own account). Only new private messages from people the daemon
wrote to, never a group or a channel, at most 100 per call:
{"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: the paths these routes serve.
- The public mesh: receipts, audits and trust.
- Connect a daemon.