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.
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 --jsonvenom 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.
What the cookie reaches
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 |
Related pages
- Approvals and questions
- Server API overview: tokens, Host check and
--host - Operations: the server proof
venom serve pairuses