Skip to content
Docs menu

Inbox and phone approvals

Read and answer the host's decision inbox over HTTP, pair a phone with the venom serve inbox page, and bridge the inbox to a Matrix room.

View .md

The inbox holds the decisions only a person can make, from every local venom session on the machine: permission prompts, questions, stuck runs, merges waiting for review, session leases. It is the host's, not a workspace's, so the server's roots don't narrow it. venom serve exposes it over HTTP and as a page for your phone.

The inbox

Operation Route What
listInbox GET /v1/inbox {items}: the open items, highest rank first (venom inbox list --json prints the same)
getInboxItem GET /v1/inbox/{id} One item, by id or a unique prefix. 404 inbox_item_not_found
resolveInboxItem POST /v1/inbox/{id}/resolve Answer it. 400 for a bad action, 409 inbox_item_resolved

An item has id, kind (approval, question, merge, lease), title, detail, agent (who is waiting), session, cwd, pid, blast (1 cosmetic to 5 irreversible or shared), uncertainty (1 obvious to 5 no idea), createdAt (Unix ms) and rank = blast × uncertainty × (1 + minutes blocked).

The answer body is {action, message?}:

action Effect
approve The agent goes on
reject It is refused; message is the reason
redirect Refused, with the instruction in message (required)
take-over The agent stops and waits for you
curl -s $S/v1/inbox -H "Authorization: Bearer $TOKEN"
curl -s -X POST $S/v1/inbox/7c2e/resolve -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"action": "redirect", "message": "Use the staging database."}'
for item in client.inbox():
    print(item["rank"], item["kind"], item["title"])
client.resolve_inbox_item("7c2e", "approve")
const items = await client.listInbox();
await client.resolveInboxItem(items[0]!.id, "reject", "Not this week.");

On your phone

GET /v1/mobile (getMobilePage) is a page for a phone: the open inbox items plus every served session's pending approvals, with one-tap answers and live updates. A phone can reach it only when venom serve listens on your network (--host 0.0.0.0 or a LAN address). The server speaks plain HTTP, so do that on a network you trust or put TLS in front.

Pairing

A browser can't hold the server token, so a token holder pairs the phone:

venom serve --root ~/work --host 0.0.0.0 --pair     # prints a QR code once listening
venom serve pair                                     # another one later, against a running server
venom serve pair --url http://127.0.0.1:8790 --json

venom serve pair checks the server with POST /v1/auth/proof, then calls POST /v1/mobile/pairings (createPairing, bearer token only) and prints the first link as a QR code. --url defaults to VENOM_SERVE_URL, else http://127.0.0.1:8790; --json prints the pairing instead:

{
  "code": "Zm9vYmFy…", "expiresAt": "2026-11-03T10:02:00Z",
  "path": "/v1/mobile#pair=Zm9vYmFy…",
  "urls": ["http://192.168.1.20:8790/v1/mobile#pair=Zm9vYmFy…"],
  "reachable": "lan"
}

The code works once, for 2 minutes; the last 8 unused codes stay valid. It travels in the URL fragment, which browsers never send, so it appears in no request line, log or Referer. reachable: this-machine means the server listens on loopback and a phone can't reach it. Pairing links use --public-url (or VENOM_SERVE_PUBLIC_URL, or serve.public_url) when set; the server never guesses a public address.

The page trades the code at POST /v1/mobile/session (pairMobile, no auth; the code is the credential; 401 pairing_invalid for an unknown, used or expired code) for a cookie named venom_mobile_<port>: HttpOnly, SameSite=Strict, Path=/v1/mobile, 12 hours, Secure behind a proxy that sends X-Forwarded-Proto: https. Paired phones live in memory: a restart unpairs them, and at most 16 stay paired.

The cookie authorizes the /v1/mobile/* routes and nothing else: no sessions, no prompts, no new pairings. These routes also accept the bearer token.

Operation Route What
getMobileInbox GET /v1/mobile/inbox {items, approvals, csrf?, expiresAt?}: inbox items and served sessions' pending approvals (each with sessionId and cwd)
streamMobileEvents GET /v1/mobile/events SSE: event: inbox with the same JSON at once and on every change (served approvals at once, inbox files within 2 s)
answerMobile POST /v1/mobile/answer {kind: "inbox", id, action, message?} or {kind: "approval", sessionId, approvalId, action, feedback?, rule?, rules?}
unpairMobile DELETE /v1/mobile/session Forget this phone's cookie: {paired: false}

A cookie's POST and DELETE requests must also carry the pairing's CSRF token (csrf from the inbox) in x-venom-csrf and come from the same origin, else 403 csrf_failed. Every answer from a phone is logged. The page sends a strict Content-Security-Policy, X-Frame-Options: DENY and Referrer-Policy: no-referrer, and makes no external request.

getMobilePage, pairMobile, unpairMobile, streamMobileEvents and answerMobile are marked x-venom-browser: the page uses them and the clients have no methods for them. The clients do have createPairing() / create_pairing() and mobileInbox() / mobile_inbox().

Matrix

With these variables set, venom serve posts inbox items to a Matrix room, and approve <id>, reject <id> [why], redirect <id> <instruction> or take-over <id> replies from the listed users answer them. Setting the homeserver without the other three stops the server at start.

Variable What
VENOM_MATRIX_HOMESERVER The homeserver URL
VENOM_MATRIX_TOKEN The bot account's access token
VENOM_MATRIX_ROOM The room id
VENOM_MATRIX_USERS Comma-separated Matrix user ids whose replies count