# How to install your agent in the VM

Install a coding agent inside a running agent-dev VM and register the i9 MCP
tools with it.

The image ships no agent. For the reason, see
[How the /vm surface works](architecture.md#a-vm-with-no-agent-in-it).

## Prerequisites

- i9 installed in `~/.i9/bin/i9`. See [How to start a VM](how-to-start-a-vm.md).
- Your agent's API key, in your clipboard or in a file that holds only the key.

## Step 1: Store the agent's credential on the host

Keep the agent's API key in the i9 secret store, not in a file you copy into
the guest or on a command line. `i9 secret set` reads the value from stdin.
Run it, paste the key, press Enter, then press Ctrl-D:

```sh
~/.i9/bin/i9 secret set ANTHROPIC_API_KEY
```

If the key is in a file that holds only the key, pass the file instead:
`~/.i9/bin/i9 secret set ANTHROPIC_API_KEY --from-file <path-to-key-file>`.

Use the variable name your agent reads (`OPENAI_API_KEY` for Codex,
`GEMINI_API_KEY` for Gemini). `i9 secret set` stores a provider's key in proxy
mode: the guest holds only the stand-in token, and i9 puts the real value into
the request as it leaves for the provider's hosts, so the value never enters
the guest, argv, a trace span, a trace archive or a snapshot. One exception: a
provider's own error can echo a redacted form of the real key (OpenAI's first 8
and last 4 characters, for example), and that fragment reaches the guest; it is
a fingerprint of the key, not the key. A secret that is
not a provider key is stored as a file and environment value instead; that
value does enter the guest, stays readable for the VM's life, and a snapshot
taken after the agent read it holds it in guest memory. `i9 secret --help-all`
lists the modes.

## Step 2: Start the VM with the credential

A VM receives only the secrets named when it starts, and the installer's VM
was started without any. Stop it, then start the image again with the name:

```sh
~/.i9/bin/i9 vm stop "$(cat ~/.i9/run/vm.url)" --discard
~/.i9/bin/i9 run https://a.i9.io/vm/manifest.json --detach --secret ANTHROPIC_API_KEY
URL="$(cat ~/.i9/run/vm.url)"
```

`i9 run` writes the new VM's URL to `~/.i9/run/vm.url`. In this VM the agent
reads a stand-in token as `$ANTHROPIC_API_KEY` and at
`/run/i9/secrets/ANTHROPIC_API_KEY`. Install the agent in this VM, in the
next step: an agent installed in another VM is not in it.

## Step 3: Install the agent in the guest

`i9 vm exec` has no default deadline: like `ssh`, it runs until the command
exits, so an install that runs for minutes needs no flag. To bound a command,
pass `--timeout-ms <ms>` before the `--`. After the `--`, the flag goes to the
guest command.

Over MCP, give `i9_vm_exec` a `timeoutMs` long enough for the command: pass
`timeoutMs: 600000` for each install below.

`exec` runs in the guest as `dev`, not root, so the `npm install -g` rows use
`sudo`: without it npm cannot create `/usr/lib/node_modules/<pkg>` and exits
`EACCES`. `sudo` needs no password in this image.

Run the command for your agent:

| Agent | Install command |
|-------|-----------------|
| Claude Code | `~/.i9/bin/i9 vm exec "$URL" --shell -- 'curl -fsSL -o /tmp/claude-install.sh https://claude.ai/install.sh && bash /tmp/claude-install.sh'` |
| Codex | `~/.i9/bin/i9 vm exec "$URL" -- sudo npm install -g @openai/codex` |
| Gemini | `~/.i9/bin/i9 vm exec "$URL" -- sudo npm install -g @google/gemini-cli` |
| OpenCode | `~/.i9/bin/i9 vm exec "$URL" -- sudo npm install -g opencode-ai` |
| Pi | `~/.i9/bin/i9 vm exec "$URL" -- sudo npm install -g @earendil-works/pi-coding-agent` |
| Hermes | `~/.i9/bin/i9 vm exec "$URL" -- pip install --break-system-packages --no-cache-dir hermes-agent` |

OpenCode's stock permissions auto-reject `external_directory`, so its first
read outside the project directory (for example `/etc`) ends the turn. Allow
`external_directory` in the OpenCode config in the guest before you rely on the
i9 workflow.

## Step 4: Register the i9 MCP tools

Run `i9 agent install` in the guest with the name of your agent. This example
registers Claude Code:

```sh
~/.i9/bin/i9 vm exec "$URL" -- i9 agent install --harness claude-code
```

The names for the agents in step 3 are `claude-code`, `codex`, `gemini`,
`opencode`, `pi`, and `hermes`.

For Hermes, `i9 agent install` prints a configuration snippet to paste into
`~/.hermes/config.yaml` — you must paste it yourself. For Gemini, the server
is registered but disabled by folder trust until you trust the project
folder in the Gemini UI. For the others it writes the configuration itself;
for Codex that is an `[mcp_servers.i9]` table appended to
`~/.codex/config.toml`.

`i9 agent list` shows all eight harnesses the binary knows about
(claude-code, codex, gemini, opencode, hermes, pi, copilot, kiro).
Copilot and Kiro have no in-guest install in the table above; where they
are installed, `i9 agent install --harness copilot` (or `kiro`) writes
the registration itself.

## Verify

List the agents in the guest and their registration state:

```sh
~/.i9/bin/i9 vm exec "$URL" -- i9 agent list
```

The row for your agent shows that it is detected and whether i9 is registered
in it.

## Troubleshooting

| Problem | Cause | Fix |
|---------|-------|-----|
| The install stops at a time limit | `--timeout-ms` bounds the call, or it follows the `--` and the guest command receives it | Raise or drop `--timeout-ms`, and put it before the `--`. Over MCP, raise or drop `timeoutMs` |
| The install or the registration exits non-zero | The agent's own installer failed in the guest | Read the command's stderr. It comes from the agent's installer |
| `vm exec` cannot connect | The session is not running | Start it again. See [How to start a VM](how-to-start-a-vm.md) |

For the registered tools, see [MCP tools](mcp-tools.md). For the flags of
`i9 vm exec` and `i9 agent install`, see the
[CLI reference](cli.md#i9-vm-exec).
