<!-- AUTO-GENERATED by codegen-agent-api.py — do not edit -->
# i9 In-Sandbox MCP Tool Reference

The tools a **running session** serves at `POST /mcp`, for an agent
driving that one VM from the inside.

Generated from the same source as the tool descriptors themselves,
so this page and the running server cannot disagree.

## How this differs from the host control plane

Two MCP surfaces exist and they are not interchangeable:

| | this page | [mcp-tools.md](mcp-tools.md) |
|---|---|---|
| served by | a running session, `POST /mcp` | `i9 mcp serve`, stdio |
| scope | one VM, from inside | the host: create, list, snapshot, stop |
| defined by | the in-sandbox agent API | the host CLI's own commands |
| gate | requires `I9_AGENT_TOKEN` set on the session | `--write-tools` for durable writes |

An agent typically needs both: the host plane to get a sandbox at all
(see the three-step handshake in `mcp-tools.md`), then this plane to
drive it.

**This endpoint is disabled unless `I9_AGENT_TOKEN` is set** and returns 404,
so a session started without one serves none of the tools below.

## Read verbs

The `write: false` descriptors, served over HTTP GET.

| Tool | Verb | Description |
|------|------|-------------|
| `i9_ping` | `ping` | One guest-agent ping RPC — returns the full clocksource/tick probe (clocksource, monoDelta, cntvctDelta, jiffies, timerIrq, tick state) used to diagnose restore liveness BEFORE anything else touches the guest. A restored guest services exactly one RPC before any wedge would show, so this is the decisive pre-exec health read. |
| `i9_state` | `state` | Status of this VM (running/paused/phase/memory). |
| `i9_snapshots` | `snapshots` | Enumerate snapshots by scanning the snapshot directory (options.snapshotDir, or the same ~/.i9/snapshots default the snapshot-write routes use). Real data only — no in-memory shadow index. Newest first. |
| `i9_counters` | `counters` | Every counter channel's cumulative totals at one cut, read from the counter nodes of this session's archive alone — no per-request span is decoded. The cut is the latest at or before `at` (the archive's latest by default); every data point carries that cut as i9.count.cut_seq, and a channel the cut did not change carries the totals from its last change (i9.count.changed_seq). The body is an OTLP-JSON metrics request. Read-only. |
| `i9_trace_tail` | `traceTail` | This session's spans as OTLP-JSON ExportTraceServiceRequest messages over server-sent events, one ResourceSpans batch per event (`event: spans`, `id:` the seq the batch ends at, `data:` the JSON). `channel` filters by registry channel name (`i9 schema io-channels`); `where` filters by a VDSL program (`i9 docs vdsl`); `since` (or Last-Event-ID) resumes after a seq an earlier event stated. The first event is sent at once, even with no spans, so the cursor is known; a store rebuilt since the cursor is announced by `event: reset`; a reader that fell behind is told by an `i9.gap` span event whose i9.count.suppressed counts the spans dropped. Each span carries i9.trust and i9.completeness. Read-only. Over MCP (`i9_trace_tail`) one call returns the events the store holds now and ends. |

## Write verbs

The `write: true` descriptors, served over HTTP POST. The flag tracks the HTTP method, not whether VM state actually changes — read the summary.

| Tool | Verb | Description |
|------|------|-------------|
| `i9_exec` | `exec` | Run a command in the guest, argv-native. Returns a jobId; poll for the result. |
| `i9_snapshot` | `snapshot` | Capture a VM snapshot to an i9io archive. Returns a jobId; poll for the result. |
| `i9_restore` | `restore` | Restore the VM from an i9io snapshot archive. |
| `i9_pause` | `pause` | Pause the running VM (vCPUs stopped; memory/device state held). |
| `i9_resume` | `resume` | Resume a paused VM. Also resumes a parked VM — same route, decided by the VM's state. |

## Not exposed as tools

MCP tools are request/response, so the agent API's
streaming verbs have no descriptor and are reached directly:

- `spans` — `WS /ws/spans`. Live trace-span firehose. WebSocket; optional where/target filters.

_10 tools (5 read, 5 write), from 11 agent-API verbs._
