---
title: Inbox and phone approvals
description: 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.
section: server-api
order: 70
audience: [builder, operator, user]
sources: [packages/harness-server/openapi.yaml, packages/harness-server/src/mobile.ts, packages/harness-server/src/mobile-page.ts, packages/harness-server/src/matrix.ts, docs/inbox.md]
features: [server-api.inbox, server-api.mobile]
---

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 {#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 |

```bash
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."}'
```

```python
for item in client.inbox():
    print(item["rank"], item["kind"], item["title"])
client.resolve_inbox_item("7c2e", "approve")
```

```ts
const items = await client.listInbox();
await client.resolveInboxItem(items[0]!.id, "reject", "Not this week.");
```

## On your phone {#mobile}

`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 {#pairing}

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

```bash
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:

```json
{
  "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 {#cookie}

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 {#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](/docs/server-api/approvals-and-questions.md)
- [Server API overview](/docs/server-api.md#auth): tokens, Host check and `--host`
- [Operations](/docs/server-api/operations.md#proof): the server proof `venom serve pair` uses
