Skip to content
Docs menu

Daemon API reference

Every route a daemon calls on Venom Cloud under /api/mesh/v1, with its authentication, request and response bodies, and errors.

View .md

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[].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:

{
  "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
}
  • 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).

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.