# Getting started with the agent-dev VM

By the end of this tutorial, you have started an i9 agent-dev VM on your
machine, run a command inside it, and stopped it.

The agent-dev VM is a Linux virtual machine with its own kernel and
filesystem, isolated from your machine. To learn why it works the way it
does, see [How the /vm surface works](architecture.md).

## Prerequisites

- A Linux x86_64 or arm64 host with a readable `/dev/kvm`, or an Apple
  silicon Mac. This tutorial uses the detached mode, which Windows does not
  have.
- `curl`, and `sha256sum` or `shasum`, on your `PATH`.

## Step 1: Check your host

Print the operating system and the architecture:

```sh
uname -s; uname -m
```

Expected output on a Linux x86_64 host:

```text
Linux
x86_64
```

A Linux arm64 host prints `aarch64` or `arm64` on the second line. An Apple
silicon Mac prints `Darwin` and `arm64`.

On Linux, confirm that you can read `/dev/kvm`. On a Mac, go to step 2.

```sh
[ -r /dev/kvm ] && echo KVM_OK
```

Expected output:

```text
KVM_OK
```

## Step 2: Start the VM

Run the installer in detached mode. `I9_DETACH=1` goes on `sh`, the side of the
pipe that runs the installer.

```sh
curl -fsSL https://i9.io/vm | I9_DETACH=1 sh
```

The installer downloads the i9 binary, checks its SHA-256, installs it at
`~/.i9/bin/i9`, starts the VM in the background, and returns your prompt.

Expected output on a Linux x86_64 host, with a download progress bar after
the first line. `TAG` is the release tag, `PATH` is `~/.i9/bin/i9`, and
`SESSION` is the process id of the new session:

```text
[i9] downloading i9-linux-x86_64 (TAG)
[i9] installed PATH — sha256 matches signed release TAG
[i9] add to PATH: export PATH="~/.i9/bin:$PATH"
  exec:      i9 vm exec vm -- <command>
  save:      i9 vm save vm
  rewind:    i9 vm rewind vm [snapshot]
  fork:      i9 vm fork vm
  stop:      i9 vm stop vm
  trace:     i9 trace tail --session SESSION
  help:      i9 help vm · i9 docs · i9 mcp serve
[i9] VM vm is live — check: "PATH" vm exec "$(cat "~/.i9/run/vm.url")" -- echo ok
URL
```

The seven indented lines are the command block that `i9 run` prints. The
binary name in the first line matches your platform. The installer names
the session `vm`, so the block addresses it by name and is ready to
copy-paste. The last line on stdout is the session URL (`URL` above),
which starts with `ws://` or `wss://` — `i9 run` prints it just before
the block, and the installer captures that line and reprints it last.

A host that already has the signed binary prints this in place of the
download and install lines:

```text
[i9] already installed: PATH matches release TAG
[i9] add to PATH: export PATH="~/.i9/bin:$PATH"
```

If a VM named `vm` is already running, the installer does not start a second
one. `i9 run` prints this line before the command block, and the rest of the
output is the same:

```text
i9: note — sandbox 'vm' is already running; no second VM was started
```

If this step exits with an error, the reason is on stderr. See
[How to troubleshoot setup](how-to-troubleshoot-setup.md).

## Step 3: Add i9 to your PATH

The installer printed the export line. Run it so the rest of this tutorial
can use bare `i9`:

```sh
export PATH="$HOME/.i9/bin:$PATH"
```

To make this permanent, add the same line to your shell's startup file
(`~/.bashrc`, `~/.zshrc`, or equivalent).

## Step 4: Confirm the session is running

List the sessions on this machine:

```sh
i9 vm ls
```

The list includes a row named `vm`.

## Step 5: Run a command in the VM

`i9 run` saved the session URL in `~/.i9/run/vm.url`. Use it to run a
command inside the guest:

```sh
i9 vm exec "$(cat ~/.i9/run/vm.url)" -- echo ok
```

Expected output:

```text
ok
```

## Step 6: Stop the VM

```sh
i9 vm stop "$(cat ~/.i9/run/vm.url)"
```

The command saves the session to a parked archive, shuts the VM down, and
prints the archive path as its only stdout line, so
`ARCHIVE="$(i9 vm stop "$(cat ~/.i9/run/vm.url)")"` captures it:

```text
ARCHIVE
```

`ARCHIVE` is a `.i9io` file under `~/.i9/state/parked/`. On stderr the command
says `VM stopped; snapshot saved to ARCHIVE` and prints a next-step hint:

```text
hint: Resume this session later from the saved archive. Run: i9 run ARCHIVE --session
```

Hints print on stderr whether it is a terminal, a pipe, or a file. A
terminal shows every next-step hint; anything else shows up to three per
command. Each hint has a per-home show limit, so repeating an action
eventually stops repeating its hint.

To stop a VM without saving a parked archive, use `i9 vm stop --discard`.

You have started an agent-dev VM, run a command in it, and stopped it.

## How long each step takes

These figures were measured on Linux arm64 with host caches not flushed,
using the `i9` of stable `v2026.10.16.000413-f59e19d61`. Each figure is the median of n
runs; a different host, network or load gives different numbers, and none
of them is a guarantee:
- Install, cold (a fresh home): 3519 ms, median of 3 runs.
- Install, warm (the binary already installed): 1469 ms, median of 5 runs.
- First start of the VM, in a fresh home: 2717 ms, median of 5 runs.
- First `i9 vm exec -- echo` after that start: 635 ms, median of 5 runs.
- Warm `i9 vm exec -- echo` on the running VM: 76.7 ms, median of 5 runs.

To measure your own host, run the script in
[How to measure startup on your host](how-to-measure-startup.md) with the path
of your `i9`. It prints the platform and the median and run count of each figure
above.

## Next steps

- [How to install your agent in the VM](how-to-install-your-agent.md): put a
  coding agent in the guest and connect it to the i9 MCP tools.
- [How to start a VM](how-to-start-a-vm.md): open an attached shell, name a
  session, or start on Windows.
- [Installer reference](installer.md): every mode, variable, file, and message.
- [How the /vm surface works](architecture.md): the design behind the one-line
  install.
