# How to install the i9 binary manually

Download the i9 binary yourself, check its SHA-256, and boot the agent-dev VM
without the installer script.

For the one-line install, see [How to start a VM](how-to-start-a-vm.md).

## Prerequisites

- A supported host: Linux x86_64 or arm64 with a readable `/dev/kvm`, or an
  Apple silicon Mac.
- `curl`, and `sha256sum` or `shasum`.
- An interactive terminal (step 5 uses `--terminal`). Without one, use
  `--detach` instead.

## Step 1: Find your binary and its hash

Fetch the releases page:

```sh
curl -fsSL https://i9.io/vm/releases
```

The page lists the current release first, then the newest pre-release build,
then every earlier stable release. Each release has a table with one row per
platform: the binary's link, its size and its SHA-256, taken from that
release's signed `release.json`. A browser gets the same page as HTML.

## Step 2: Download the binary the VM image was built with

The VM image and the i9 binary come from one release: the binary on your host
and the agent inside the guest are the same build. The stable installer
installs the release named in the file name of your architecture's image. Read
your architecture's `version` from the manifest:

```sh
curl -fsSL https://a.i9.io/vm/manifest.json
```

Each entry under `images` (`arm64`, `x86_64`) carries a `version` such as
`YYYY.MM.DD.HHMMSS-<sha9>`. The binary for that release is under
`i9/v<version>/`. This example downloads the Linux x86_64 binary; for the
other names, see [Binaries](installer.md#binaries).

Set `V` to the `version` value from your architecture's entry above, then
download:

```sh
V=PASTE_VERSION_HERE
mkdir -p ~/.i9/bin
curl -fSL "https://a.i9.io/i9/v$V/i9-linux-x86_64" -o ~/.i9/bin/i9
```

`i9/latest/` holds the newest build, which can be newer than the VM image the
manifest names. The stable installer uses the release path for the same
reason.

## Step 3: Check the SHA-256

On Linux:

```sh
sha256sum ~/.i9/bin/i9
```

On macOS:

```sh
shasum -a 256 ~/.i9/bin/i9
```

Compare the result with the SHA-256 column of the releases page. The same
value is the first word of the binary's sidecar file:

```sh
curl -fsSL "https://a.i9.io/i9/v$V/i9-linux-x86_64.sha256"
```

The installer checks against the signed `release.json` of the release instead.
That file lists the sha256 and size of each binary, and its signature is in
`release.json.sig`:

```sh
curl -fsSL "https://a.i9.io/i9/v$V/release.json"
```

To verify the signature yourself, follow the steps at
https://i9.io/vm/verify.

## Step 4: Make the binary executable

```sh
chmod +x ~/.i9/bin/i9
```

On macOS, a binary downloaded with `curl` as above carries no quarantine attribute, so it runs as it is. The published binary is already signed. Don't sign it again.

## Step 5: Boot the VM

Pass the manifest URL as the target. `i9 run` resolves it to the image for
your architecture. From an interactive terminal:

```sh
~/.i9/bin/i9 run https://a.i9.io/vm/manifest.json --terminal
```

Without a terminal (CI, a container, an agent's tool call), use the
detached form:

```sh
~/.i9/bin/i9 run https://a.i9.io/vm/manifest.json --session --detach
```

The first run streams the VM image from `a.i9.io`; later runs use the
cached image under `~/.i9/`. Stopping the VM saves the session to a
parked archive under `~/.i9/` (use `vm stop --discard` to skip the
archive). To remove everything i9 wrote: stop any running VM, run
`~/.i9/bin/i9 uninstall --dry-run` to see what would go, then
`~/.i9/bin/i9 uninstall --force`. Plain `i9 uninstall` removes the binary,
`~/.i9/`, the agent wiring and the per-run state, but refuses while saved
snapshots, session traces or the secrets store exist; `--force` deletes
those too.

By default, fetching the VM image sends a telemetry beacon (OS, CPU
architecture, i9 version) with no identifier. Turn it off with
`i9 config set telemetry.enabled false` (one run: `DO_NOT_TRACK=1`).

## Windows

The download page also lists a Windows x86_64 binary
(`i9-windows-x86_64.exe`). The steps above are written for Linux and
macOS; on Windows, use the PowerShell installer in
[How to start a VM](how-to-start-a-vm.md#start-on-windows). The VM boots
attached to your terminal, and Windows has no detached mode.

Windows has the least verification of the supported hosts. The
[support matrix](support-matrix.md) records one run by hand on Windows Server
2022 with the published `i9.exe`: run, exec, save, rewind, exec again and stop.
No scheduled test repeats that run. `i9 vm cp` and `i9 vm ports`
are not verified on Windows. Stopping a VM after a rewind can take about ten
minutes to return; that is a current limit of the Windows backend, not a
refusal.

## Verify

Check the install:

```sh
~/.i9/bin/i9 doctor
```

`i9 doctor` exits 0 when every required check passes. It verifies the
binary's packed payloads and reports what the host can do with a guest.

### The VM image

The `blake3` in `vm/manifest.json` is a transfer check. The image's own trust
anchor is the signature on the image archive: `i9 run` checks it before it
restores anything, and refuses a signer it does not trust (see
"Archive trust" at https://i9.io/vm/security). To see the verdict for a VM you
started, pass the PID that `i9 run` printed on its `trace:` line:

```sh
~/.i9/bin/i9 trace search i9.archive.trust_check --internal --session <PID> --fields kid,trust,provenance_mode
```

`trust=authority` means the image is signed by an enrolled i9.io key.

## Troubleshooting

| Problem | Cause | Fix |
|---------|-------|-----|
| The SHA-256 differs from the page | The download is incomplete, or a release was published between the two requests | Fetch the download page again, then download again |
| The SHA-256 column shows `(not yet published)` | The binary has no sidecar file, in its release or in `i9/latest/` | Compare with the binary's entry in the release's `release.json` |
| `i9 run` says the manifest has no image for this host | The manifest carries no entry for your architecture | See [Manifest reference](manifest.md) for the published architectures |

For the flags of `i9 run`, see the [CLI reference](cli.md#i9-run).
