# Installer reference

The shell script that `https://i9.io/vm` and `https://i9.io/vm/install.sh`
serve: its hosts, variables, start modes, files, exit status, and messages.

For task-oriented steps, see [How to start a VM](how-to-start-a-vm.md). For
the routes, see [Routes reference](routes.md).

## Supported hosts

| `uname -s` | `uname -m` | Binary | Requirement |
|------------|------------|--------|-------------|
| `Linux` | `x86_64` | `i9-linux-x86_64` | Readable `/dev/kvm`, and a `userfaultfd` the user can open |
| `Linux` | `aarch64` or `arm64` | `i9-linux-arm64` | Readable `/dev/kvm`, and a `userfaultfd` the user can open |
| `Darwin` | `arm64` | `i9-darwin-arm64` | None |

On any other host the script exits 8 (`EPLATFORM`). Every host also needs
`curl`, `mktemp`, and `sha256sum` or `shasum`. A Windows x86_64 host uses the
Windows installer, described at the end of this page.

## Binaries

The script downloads one file, `https://a.i9.io/i9/TAG/FILE`, where `TAG` is
the release tag in the signed release data the server renders into the script.

| Platform | Architecture | File |
|----------|--------------|------|
| Linux | x86_64 | `i9-linux-x86_64` |
| Linux | arm64 | `i9-linux-arm64` |
| macOS | Apple silicon | `i9-darwin-arm64` |
| Windows | x86_64 | `i9-windows-x86_64.exe` |

## Verification

Each release's file sizes and SHA-256 digests are signed with the i9 release
key (ECDSA P-256). The server verifies the signature and checks the release
against its rollback floor before it writes the digests into the script's
release data block, between the `# >>> release data` and `# <<< release data`
markers. The script compares the SHA-256 of the downloaded file with the digest
in that block, and installs the file only when the two are equal. A release
that is unsigned, withdrawn, or older than the rollback floor produces a script
that refuses with `EREFUSED` before it downloads anything. To check the
signature independently of the script, see `https://i9.io/vm/verify`.

## Sequence

The script runs under `set -eu` and performs these steps in order:

| Step | Action |
|------|--------|
| 1 | Validates `I9_CHANNEL`, `I9_NO_BOOT`, `I9_DETACH` and `I9_AGENT`; any other value exits 2 (`EUSAGE`) |
| 2 | Detects the host and selects the release data for the channel, host and architecture |
| 3 | Creates `$I9_HOME` with mode `0700` when it does not exist, and `$I9_HOME/bin` |
| 4 | When `$I9_HOME/bin/i9` exists and its SHA-256 equals the signed digest, skips steps 5 to 7. The script does not use an `i9` already on `PATH` |
| 5 | Downloads the binary to a `mktemp` file `$I9_HOME/bin/.i9.XXXXXX`, limited to the signed size |
| 6 | Compares the file's SHA-256, from `sha256sum` or from `shasum -a 256` when `sha256sum` is absent, with the signed digest. A difference exits 4 (`EVALIDATION`) and installs nothing |
| 7 | Marks the file executable and renames it to `$I9_HOME/bin/i9`. On macOS, clears the file's extended attributes. The script does not sign the binary |
| 8 | Prints to stderr what the i9 MCP server gives an agent and the `i9 agent install --write-tools` command. Runs that command only with `I9_AGENT=1`, or after a `y` answer to its question when `/dev/tty` opens; never under a custom `I9_HOME`. A failed registration does not stop the install |
| 9 | With `I9_NO_BOOT=1`, prints the `PATH` line to stderr and the binary's path to stdout, and exits 0 |
| 10 | Exits 6 (`EREFUSED`) when the channel has no VM image. Runs `i9 --json doctor` and exits 8 (`EPLATFORM`) unless it reports `can_run`: on Linux that needs a readable `/dev/kvm` and a `userfaultfd` this user can open |
| 11 | Starts the VM in one of the start modes below |

## Channels

`I9_CHANNEL` selects the release data: `stable` (the default) or `edge`.

| Channel | Release installed | VM image |
|---------|-------------------|----------|
| `stable` | Per architecture, the release in the file name of that architecture's image in `vm/manifest.json` | That image |
| `edge` | The release named by `i9/latest/release.json` | The stable image of the same architecture when its release is not newer than the edge release; otherwise none |

A channel with no VM image installs the binary with `I9_NO_BOOT=1` and
refuses to start a VM without it. For either channel, the server reads the
release's signed `release.json` and writes its digests into the script. See
[Routes reference](routes.md#assets-the-vm-pages-use) and
[Manifest reference](manifest.md).

## Environment variables

| Variable | Default | Effect |
|----------|---------|--------|
| `I9_HOME` | `$HOME/.i9` | The directory the script installs into and writes state under: `bin/` and `run/`. It is the directory the `i9` binary uses for its own state |
| `I9_CHANNEL` | `stable` | `stable` or `edge`. Any other value exits 2 |
| `I9_NO_BOOT` | Unset | `1` installs the binary and starts no VM. Any other non-empty value exits 2 |
| `I9_DETACH` | Unset | `1` selects the detached mode. Any other non-empty value exits 2 |
| `I9_AGENT` | Unset | `1` registers the i9 MCP server in every detected agent harness without asking (`i9 agent install --write-tools`). Unset, the script asks at a terminal and only prints the command otherwise. Any other non-empty value exits 2 |
| `I9_SESSION_NAME` | `vm` | The session name in the detached mode, and the base name of the URL file |

The script reads these variables from its own environment, the `sh` side of
`curl ... | sh`.

## Start modes

`IMAGE` is the VM image address in the release data. `NAME` is the session
name.

| Mode | Selected when | Command the script runs |
|------|---------------|-------------------------|
| Detached | `I9_DETACH=1`, or stdin is not a terminal and `/dev/tty` cannot be opened | `i9 run IMAGE --session --name NAME --no-viewer-gate --detach` |
| Attached | Every other case | `i9 run IMAGE --terminal`, with stdin from `/dev/tty` |

In the attached mode, the script replaces itself with the `i9 run` command, so
the exit status is that command's.

### Guest size

In both modes, and in the Windows installer, the script passes no size to
`i9 run`. The VM image resumes from a checkpoint, so the VM has the size of
that checkpoint: 2048 MiB of memory and 2 vCPUs. To start the image at a
different size, run `i9 run` yourself with `--memory` or `--vcpus`. A
different size causes a cold boot: the guest starts from the beginning,
without the processes of the checkpoint, and takes longer than a resume. A
cold boot needs the same host features as a resume, `userfaultfd` included,
so it does not start a VM on a host where a resume fails for that reason.

### Detached mode

The script runs under `umask 077`. `i9 run --detach` starts the VM in its own
session and returns once the VM reports ready. The last line of its stdout is
the session URL. `i9 run` itself writes that URL to `$I9_HOME/run/NAME.url`,
replacing any earlier file. The script prints a `[i9] VM NAME is live` line to
stderr that names a `vm exec` check, prints the URL to stdout, and exits 0.

When `i9 run --detach` fails, the script exits 7 (`ESERVER`) with
`the VM did not come up`. The reason is on stderr above that line.

## Output

| Stream | Content |
|--------|---------|
| stdout | With `I9_NO_BOOT=1`, the path of the installed binary. In the detached mode, the session URL as the last line |
| stderr | Progress and error messages, each with the prefix `[i9]`, and the download progress bar |

The session URL starts with `ws://` or `wss://`.

## Files

In this table and in the sequence above, `$I9_HOME` is the value of `I9_HOME`, or `$HOME/.i9` when it is unset or empty.

| Path | Written | Content |
|------|---------|---------|
| `$I9_HOME` | When it does not exist | Created with mode `0700`. An existing directory keeps its mode |
| `$I9_HOME/bin/i9` | Every run whose binary passes verification | The i9 binary |
| `$I9_HOME/bin/.i9.XXXXXX` | Each download. Removed on exit unless renamed | The downloaded binary, a `mktemp` file, before verification |
| `$I9_HOME/run/NAME.url` | Every `i9 run`, attached or detached, once the control URL exists. Written by `i9 run`, not by the script | The session URL. The URL names the session and carries no token (`i9 run --show-token` prints the token whole). The file has mode `0600`, in a `run/` directory with mode `0700` |

## Exit status

Every refusal the script makes prints one line, `[i9] E<NAME>: <what happened> —
<what to do>`, to stderr. The statuses are the ones in the
[CLI reference's exit-code table](cli.md#exit-codes). The `i9` binary it
installs refuses in its own form: an `error:` line, then a `hint:` line.

| Status | Name | Meaning |
|--------|------|---------|
| `0` | | Installed, and the VM started unless `I9_NO_BOOT=1` |
| `2` | `EUSAGE` | `I9_CHANNEL`, `I9_NO_BOOT`, `I9_DETACH` or `I9_AGENT` has an invalid value |
| `4` | `EVALIDATION` | The download's SHA-256 is not the signed digest |
| `5` | `ENETWORK` | The download failed, or the release could not be read; run the script again |
| `6` | `EREFUSED` | The release is not verifiably signed, was withdrawn, or is older than the rollback floor; or the channel has no VM image |
| `7` | `ESERVER` | Detached mode: `i9 run --detach` did not report the VM ready |
| `8` | `EPLATFORM` | Unsupported host, no build for this host in the release, the VM image not published for this architecture, `i9 doctor` not reporting that the host can run a guest, no hash tool, or `$I9_HOME`, `$I9_HOME/bin` or the staging file in it not creatable or writable |
| Other | | In the attached mode, the status of `i9 run` |

These are the script's statuses, and a fetch that fails never reaches the
script. With a wrong path in the URL, `curl -fsSL` prints only its own
`curl: (22) The requested URL returned error: 404` (a wrong host prints
`curl: (6) Could not resolve host: <host>`), `sh` reads an empty script, and
the pipeline `curl -fsSL <url> | sh` exits
with `sh`'s status, 0. To fail the line on a failed fetch, fetch first:
`curl -fsSL <url> -o i9-install.sh && sh i9-install.sh`, or run the pipeline
under `set -o pipefail` in bash. `sh -c "$(curl -fsSL <url>)"` does not: an
empty command string also exits 0.

## Messages

| stderr contains | Source | Meaning | Stops setup |
|-----------------|--------|---------|-------------|
| `[i9] EUSAGE:` | Script | An `I9_*` variable has an invalid value; the line names it | Yes |
| `this host is` | Script | The host is not supported | Yes |
| `has no build for` | Script | The release has no binary for this host | Yes |
| `the VM image is not published for` | Script | The release data has no entry for this architecture | Yes |
| `/dev/kvm is not readable` | Script | The Linux host has no readable `/dev/kvm` | Yes |
| `neither sha256sum nor shasum is installed` | Script | The host has no tool to verify the binary | Yes |
| `cannot create` or `cannot write in` | Script | `$I9_HOME`, `$I9_HOME/bin` or the staging file in `bin` cannot be created or written (`EPLATFORM`) | Yes |
| `download of` | Script | The binary download failed (`ENETWORK`) | Yes |
| `sha256 of the download is` | Script | The binary does not match the signed digest (`EVALIDATION`) | Yes |
| `is not verifiably signed` | Script | The release's signature does not verify (`EREFUSED`) | Yes |
| `was withdrawn` | Script | The release was withdrawn; the line gives the reason (`EREFUSED`) | Yes |
| `is older than` | Script | The release is older than the rollback floor (`EREFUSED`) | Yes |
| `could not be read just now` | Script | The release could not be read; run again (`ENETWORK`) | Yes |
| `channel has no VM image` | Script | The channel has no image; run with `I9_NO_BOOT=1` (`EREFUSED`) | Yes |
| `the VM did not come up` | Script | Detached mode: `i9 run --detach` failed (`ESERVER`) | Yes |
| `already installed` | Script | The installed binary matches the signed digest | No |
| `sha256 matches signed release` | Script | The binary was verified and installed | No |
| `booting VM image` | Script | Names the VM image it starts, the binary release and the channel. On `edge` the binary is newer than the image (see [Channels](#channels)) | No |
| `is live` | Script | Detached mode: the VM is ready | No |
| `userfaultfd unavailable` | Script, `i9 run` | This user cannot open `userfaultfd`, which every VM boot needs; `i9 doctor` names the kernel setting that refuses it | Yes |
| `does not report that this host can run a guest` | Script | `i9 doctor` reported another reason this host cannot run a guest | Yes |
| `host_kernel_no_uffd_wp` | `i9` | The host can run and restore a guest and cannot capture one | No |
| `the Windows hypervisor is not running` | Windows installer | Virtualization is off in the firmware, or Windows Hypervisor Platform is not turned on | Yes |

## Windows installer

`https://i9.io/vm/install.ps1` serves a PowerShell script for Windows
x86_64. It runs from PowerShell:

```powershell
irm https://i9.io/vm/install.ps1 | iex
```

The script reads `I9_HOME` (default `%USERPROFILE%\.i9`), `I9_CHANNEL`
(`stable` or `edge`), `I9_NO_BOOT` (`1`) and `I9_AGENT` (`1`). It has one start mode: attached.
It has no detached mode and writes no URL file.

The script runs in a scope of its own and performs these steps in order. A
step that stops the script throws a terminating error whose message is one
`[i9] E<NAME>:` line.

| Step | Detail |
|------|--------|
| Validate | `I9_CHANNEL`, `I9_NO_BOOT` or `I9_AGENT` with an invalid value throws `EUSAGE` |
| Hypervisor | Reads the Windows hypervisor state. Throws `EPLATFORM` when the hypervisor is not running. Skips the check when the state cannot be read |
| Verify | When `i9.exe` exists and its SHA-256 equals the signed digest, skips the download |
| Download | `i9-windows-x86_64.exe` to a staging file `.i9-GUID.exe` in `%I9_HOME%\bin`. A failed download throws `ENETWORK` |
| Hash | Compares the file's size and SHA-256 with the signed release data. A difference throws `EVALIDATION`. A match moves the file to `%I9_HOME%\bin\i9.exe`. The staging file is removed on exit |
| Agent | Prints what the i9 MCP server gives an agent and the `agent install --write-tools` command. Runs it only with `I9_AGENT=1`, or after a `y` answer when the console is interactive; never under a custom `I9_HOME`. A failed registration does not stop the install |
| Image | Throws `EREFUSED` when the channel has no VM image and `I9_NO_BOOT` is not `1` |
| Start | `i9.exe run IMAGE --terminal` |

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