<!-- AUTO-GENERATED by codegen-cli.py — do not edit -->
# i9 MCP Tool Reference

The tools an MCP client sees when it launches `i9 mcp serve`.

Generated from the same definitions the server builds its tool
descriptors from, so this page and the running server cannot disagree.

## Two planes

This page covers the **host control plane**: tools served over stdio by
`i9 mcp serve`, each one shelling out to an `i9` verb.

There is a second, separate surface. A **running session** serves its own
MCP endpoint at `POST /mcp` (gated on `I9_AGENT_TOKEN`), whose tools are
documented on the `mcp-agent-tools` page, which ships in the binary:
`i9 docs mcp-agent-tools`. Those act
on one VM from the inside (ping, exec, snapshot, restore, pause, resume). They come from a
separate schema, so they have
their own page.

## What needs `--write-tools`

`write` is an **opt-in gate, not a read-only/write split**. It marks tools
that mutate a durable archive, boot a VM, or rewind. Everything
else is available with no flag at all — including the whole session
lifecycle (create, exec, ls, status, fork, snapshot, park, stop), which
acts on the agent's own sandbox.

An agent therefore gets sandbox control out of the box. The gate is about
durable side effects, not about whether a tool changes anything.

## Getting a sandbox: the three-step handshake

**Read this before concluding a capability is missing.** Booting a sandbox
and driving one are separate tools, and the link between them is not
obvious from the tool list. Two independent readers have concluded from
that list that an agent cannot create a box. It can.

1. **Boot it.** `i9_run` with `session: true` (and a `name:` you choose;
   a live sandbox already under that name is reused rather than booted
   twice). For a URL or `.i9io` target the tool waits for the session's
   ready line, returns `{booted, pid, command, boot}`, and leaves the
   session running. `boot` is that line, `i9 vm: ready — <controlUrl>`,
   and the control URL in it carries the session's token. With
   `detach: true` the result is `{booted, command, session}`. Its session
   member is `{control, pid, log}`, and `control` is the same URL.
   `i9_run` is the one step behind
   `--write-tools`; steps 2 and 3 are on the default surface. So a
   harness registered with a plain `i9 agent install` can drive a
   sandbox and cannot boot one — register with
   `i9 agent install --write-tools` to get step 1. The flag is not the
   default because the entry launches `i9 mcp serve` in a harness
   nobody may be watching, and the write surface is the durable
   mutators.
2. **Address it.** `i9_vm_ls` lists live sandboxes on this machine and
   returns `{sessionId, name, pid, controlUrl, startedAtNs}` for each —
   match `name` or `pid` against the one you want. Use it for a sandbox
   another call booted: the `i9_run` result already holds the control
   URL of the sandbox it booted.
3. **Drive it.** `i9_vm_exec`, `i9_vm_fork`, `i9_vm_save`, `i9_vm_rewind`,
   `i9_vm_status` and `i9_vm_stop` take that `controlUrl` as their
   `serverUrl` argument.

A fork child is reached the same way. `i9_vm_fork` returns the
child's own `controlUrl` next to its `vmId`, and `i9_vm_ls` lists the
child beside its parent — so steps 2 and 3 address a child the way they
address the box it was forked from. Both stay drivable at once — on
macOS alike each child runs in a process of its own.
Each `i9_vm_ls` row carries `vmId`, the id fork, save and status name
the VM by, so a child's `parentId` matches its parent row's `vmId`.
Stopping or parking a child ends that child, not its parent or its
siblings. `i9_vm_rewind` is the exception: it replaces the whole
session's active vm, so it is refused on a child's `controlUrl`
(with the session's own named in the error) rather than acting on the
parent behind the caller's back.

The **Runs** column in the tables below names the `i9` verb behind each
tool, and is the reliable way to tell any two similar tools apart.

## Sandbox lifecycle

| Tool | Runs | Needs `--write-tools` | Summary |
|------|------|----------------------|---------|
| `i9_run` | `i9 run` | yes | Run a VM image as a live session, from a URL or a local path |

## Traces

| Tool | Runs | Needs `--write-tools` | Summary |
|------|------|----------------------|---------|
| `i9_trace_ls` | `i9 trace ls` |  | List recent traces, VM sessions, or one trace's archives |
| `i9_trace_search` | `i9 trace search` |  | Grep-like span search with attribute display |
| `i9_trace_show` | `i9 trace show` |  | Render a trace as a process tree, flamegraph, or diagram |
| `i9_trace_stats` | `i9 trace stats` |  | Aggregate a trace archive into stats and percentiles |

## Archives

| Tool | Runs | Needs `--write-tools` | Summary |
|------|------|----------------------|---------|
| `i9_archive_ls` | `i9 archive ls` |  | List local i9io archives and whether each one boots |
| `i9_archive_redact` | `i9 archive redact` | yes | Redact segments from an archive |

## Other

| Tool | Runs | Needs `--write-tools` | Summary |
|------|------|----------------------|---------|
| `i9_config_get` | `i9 config get` |  | Read one config key |
| `i9_config_set` | `i9 config set` | yes | Write one config key to this install's config file |
| `i9_config_unset` | `i9 config unset` | yes | Remove one config key from this install's config file |
| `i9_docs` | `i9 docs` |  | Read i9's documentation from inside the binary — no network |
| `i9_doctor` | `i9 doctor` |  | Check this install: packed payloads, host capabilities, merged config |
| `i9_feedback` | `i9 feedback` |  | Send a report about i9 to feedback.i9.io, where a person reads it |
| `i9_grant_renew` | `i9 grant renew` | yes | Renew a grant by its grant id for another 7 days |
| `i9_grant_request` | `i9 grant request` | yes | Get a free 7-day grant with no vCPU limit and install it |
| `i9_grant_show` | `i9 grant show` |  | Show the installed grant (or the free-tier default) |
| `i9_secret_check` | `i9 secret check` |  | Judge a secretspec.toml against the secret store before any VM starts |
| `i9_secret_ls` | `i9 secret ls` |  | List stored secrets by name and policy; never a value |
| `i9_secret_refresh` | `i9 secret refresh` | yes | Read a reference secret's backend again and deliver the new value to running VMs |
| `i9_secret_rm` | `i9 secret rm` | yes | Remove a secret by name |
| `i9_secret_set` | `i9 secret set` | yes | Store a secret under a name; the value comes from `fromFile` (a host path) or `ref` |
| `i9_vm_cp` | `i9 vm cp` |  | Copy files into or out of a VM's guest |
| `i9_vm_egress` | `i9 vm egress` | yes | Allow or block a host for egress on a running VM |
| `i9_vm_exec` | `i9 vm exec` |  | Run a command in a VM's guest |
| `i9_vm_fork` | `i9 vm fork` |  | Branch a running VM into two that diverge from the same state |
| `i9_vm_ls` | `i9 vm ls` |  | List VMs running on this machine |
| `i9_vm_pause` | `i9 vm pause` |  | Freeze a VM in place |
| `i9_vm_ports` | `i9 vm ports` |  | Publish or unpublish a host-to-guest port on a running VM |
| `i9_vm_resume` | `i9 vm resume` |  | Thaw a VM previously frozen by `i9_vm_pause` |
| `i9_vm_revoke_secret` | `i9 vm revoke-secret` | yes | Cut one VM off from a proxy secret without touching any other VM |
| `i9_vm_rewind` | `i9 vm rewind` | yes | Replace a VM's state from a snapshot |
| `i9_vm_save` | `i9 vm save` |  | Capture the VM's state as a snapshot — the VM keeps running |
| `i9_vm_status` | `i9 vm status` |  | Status of a VM — live over its URL, or offline from its archive |
| `i9_vm_stop` | `i9 vm stop` |  | Save the VM's state and shut it down |

_34 tools._
