# How the /vm surface works

This page explains why `https://i9.io/vm` behaves the way it does: why one
address answers three kinds of reader, why the VM image streams instead of
downloading, and why a detached start takes the care it does. It describes
design, not procedure.

For the facts, see [Routes reference](routes.md),
[Installer reference](installer.md), and [Manifest reference](manifest.md).
For a hands-on start, see [Getting started](getting-started.md).

## Overview

The product is one command: `curl -fsSL https://i9.io/vm | sh`. Behind it
sit three things. A web service answers the page routes. An object store
holds the i9 binaries, the manifest, and the VM images, and the asset host
`https://a.i9.io` serves them: the request path is the object's key. The i9
binary boots the image in a VM on the reader's own machine.

| Step | What happens |
|------|--------------|
| 1 | The shell requests `/vm` and receives the installer script |
| 2 | The service has read the manifest and the release's signed `release.json`, and wrote the release, the binary's digest and the image address into the script |
| 3 | The script downloads the i9 binary from the release that built the image (`https://a.i9.io/i9/v<version>/`), and installs it only when its SHA-256 equals the signed digest |
| 4 | The script starts `i9 run` with the image address |
| 5 | `i9 run` sends Range requests under `https://a.i9.io/vm/` and receives the byte ranges the VM reads |

Nothing in this path needs an account, root access, or a daemon. The host
needs a hypervisor, `curl`, a SHA-256 tool, and a shell.

## One address, three readers

Three readers arrive at `/vm`, and each needs a different document. A shell
pipeline needs a script. A person in a browser needs a page that says what
the script does before they run it. A coding agent needs instructions it can
follow without a terminal.

The service tells them apart by the `Accept` header. The script is the
default, because the one-line install has to work with any HTTP client that
sends `*/*` or nothing. A browser asks for `text/html` and gets the landing
page, so a person who follows a link never receives a shell script. A client
that asks for `text/markdown` gets the landing page's source.

The cost of negotiation is that the address alone does not say what comes
back. `/vm/install.sh` exists for that reason: it returns the script whatever
the client sends.

## One text, several renderings

The agent instructions exist once. The service returns them as Markdown at
`/vm/AGENTS.md`, renders the same Markdown to HTML for a browser, and places
them as the comment block at the top of the installer script. An agent that
fetches the bare `/vm` address therefore lands on the script and still reads
the full instructions.

The landing page and the agent instructions also share one list of facts:
the install command, the supported hosts, the benefits, and the failures.
The wording differs for each reader. The facts cannot, because both pages are
built from the same list. The HTML pages carry no script, so what a browser
shows is only a rendering of the Markdown.

Each i9 release carries these texts in its offline documentation, so the
documentation in a binary matches the site that release shipped with.

## Paths that do not exist say so

An unknown path answers `404` with a body that lists the paths that do exist.
This is a deliberate choice over two more forgiving designs.

Serving the installer for every path under `/vm` would mean that a typing
mistake in a `curl ... | sh` line still fetches a runnable script with a
success status. Answering an empty `200` would tell an agent that the
instructions exist and are blank. A `404` that names the real paths is the
only answer that both kinds of client can act on.

The root path `/` redirects (`302`) to the product entry — `/vm` today.
If the site ever has zero or several entries at that level, the root answers
`404` with a body that says so, rather than guessing.

## A small pointer and large immutable images

A VM image is about a gigabyte. The design avoids downloading it.
`i9 run` reads the image over HTTP Range requests and fetches only the byte
ranges the VM touches, so the VM starts without a full download.

Two properties make a repeat start cheaper than the first (the measured
figures are in [Getting started](getting-started.md)). Every image has a versioned file
name and never changes, so the service marks it immutable and caches its
chunks at the edge. The manifest is the one mutable object: a small document
that names the current image for each architecture, served with `no-cache`
so that a new publication is visible at once.

The manifest also records how each image starts. A checkpoint image holds
the saved state of a running guest, and the VM resumes from it. A cold
image runs the guest's own boot sequence.

The trade-off is that a start depends on the network. No local copy of the
image exists to fall back on.

## A fresh binary on every run

The installer ignores an `i9` already on `PATH`. It downloads the binary
unless `~/.i9/bin/i9` already has the signed SHA-256. An attached terminal and
a streamed boot both need a current binary, and an older one fails. Because
the binary and the image come from the same published release, the binary a
reader runs and the image it boots belong together.

The installer checks the download against the SHA-256 in the signed
`release.json` before it installs anything. The release key signs those
digests, and the service refuses to render an installer for a release whose
signature does not verify, so a stolen storage credential alone cannot pass
the check. It also catches a truncated or corrupted download and the wrong
binary for the platform, and it makes each of those loud. The check does not
defend against someone who controls the service that renders the script. The
binary is downloaded to a temporary file beside its destination and renamed
into place only after the check passes, so `~/.i9/bin/i9` never holds bytes
the check did not see.

The cost is a download of the binary whenever the installed file differs from
the signed release.

On macOS, the installer does not sign the binary. The published binary
already carries the signature and the hypervisor entitlement it needs.
Signing again on the reader's machine would replace that signature with a
local one, and it would fail on a Mac that lacks the developer tools.

## A detached VM has to outlive its launcher

A detached start exists for callers with no terminal: scripts, CI jobs, and
agent tool calls. Those callers share a habit. When the launching command
ends, or when a timeout fires, they signal the command's whole process group.
A plain background job stays in that group and dies with it.

So the installer runs `i9 run --detach`, which starts the VM in a session of
its own and returns once the VM reports ready. A signal to the installer's
process group does not reach the VM.

Readiness is an event, not a guess. `i9 run --detach` returns when the VM's
control address is live, and a boot that fails ends the call with a failure
instead of hanging it. The installer then exits 7 (`ESERVER`) and the startup
log path is printed above its message. On success the last line of the
command's stdout is the session URL, which `i9 run` writes to
`run/NAME.url`, owner-only, so a later command can read the address back.

The attached mode has the opposite problem. Under `curl ... | sh`, stdin is
the pipe that carries the script, so the installer attaches the guest shell
to the controlling terminal directly. A host with no controlling terminal
gets a detached VM, in place of a refusal.

## A VM with no agent in it

The image contains an operating system, the i9 binary, Node, Python, and
Docker Engine with the compose and buildx plugins. It
contains no coding agent. The VM is neutral ground: it favors no agent. Each
reader installs the agent they already use, with that agent's own installer,
and then registers the i9 MCP tools with it.

The cost is an install step in the guest, which takes minutes.

The isolation is the point of the product. The VM has its own kernel and its
own filesystem, so the agent cannot reach the host's files or processes. The
only ways across are the ones the reader opens: a published port or a copied
file.

## Hosts differ in what they can do

Running a guest, restoring one, and capturing one need different kernel
features. A host can have `userfaultfd` without its write-protect mode. Such
a host boots and runs a VM normally and cannot take a snapshot.

i9 refuses the snapshot on that host, because the alternative is an archive
that no machine can restore. `i9 doctor` reports the limit before any work
depends on it. The published /vm image, captured on another machine, still
restores there.

## A snapshot you were handed

Every archive i9 writes is signed. Three separate properties decide whether a
snapshot runs, and a refusal or a warning names each of them.

**Integrity: is the file intact?** Every segment carries its own signature
over its own content hash, and the chain links each segment to the one before
it. A truncated, corrupt, or edited archive is refused when you restore it.
There is no setting that changes this, and no flag that turns it off. [What a
snapshot guarantees](#what-a-snapshot-guarantees-and-how-it-fails) lists the
refusals word for word.

**Authenticity: who signed it?** Each install signs with a key it generates on
first use and keeps at `~/.i9/producer.seed`. Your install recognises its own
key and the i9.io publishing key, and nothing else, so a snapshot from someone
else's machine resolves to a key you do not know. The refusal or warning
names that key by its `kid`.

**Authorization: is that signer trusted to have this run?** This is the one
decision a setting controls, and it is made on who signed the archive, never on
how it reached you. A snapshot in a file on your disk and the same snapshot
fetched from a URL get the same answer, because a malicious snapshot arrives
by email, from a repository or as a download just as easily as from a server.
`provenance.mode` picks the answer for a signer you do not know:

| Mode | An unknown signer is |
|---|---|
| `strict` | refused, naming the signer |
| `interactive` | refused until you confirm that signer at a terminal |
| `development` | restored under a prominent warning |

Unset, the mode follows who is asking. An agent (MCP, `--json`, a non-TTY
stdin, a detached run) gets `strict`, because it cannot answer a prompt and a
warning in its output is easy to miss. A person at a terminal gets
`interactive`. A signer you do trust (your own, or i9.io's) is accepted in
every mode with no prompt and no warning.

```
i9 config set provenance.mode development
```

`i9 config get provenance.mode` reads it back. An unrecognised value reads as
unset, so a typo never widens trust. In `development` and after an interactive
confirmation the snapshot restores, and the warning is shown:

```
  ########################################################
  ##  !!  UNVERIFIED ARCHIVE PROVENANCE  !!             ##
  ########################################################
  restore: UNVERIFIED PROVENANCE: nobody has vouched for who wrote this …
  ########################################################
```

That is a real warning, not a formality. A snapshot is a running machine
frozen mid-life: restoring one resumes its processes, its credentials and its
code on your box. Restore a snapshot from someone you trust, in the same
sense you would run their build script. The decision is recorded on the
restore span (`provenance_mode`, `integrity`, `authenticity`,
`authorization`), so `i9 trace` shows what each restore was allowed under.

## What a snapshot guarantees, and how it fails

A snapshot is a running VM in one file: memory, processor state, device state
and the changed blocks of the VM's writable disk. This section says what holds
when the capture races a busy guest, and what the binary prints when a capture
or a restore is interrupted. Each statement is checked against the released
binary by a test that runs it, and the text in the code blocks is what the
binary prints.

**Capture under load is VM-consistent.** `i9 vm save` and `i9 vm stop` stop
every virtual CPU, drain the block device so that no request is in flight, and
record memory, processor state, device state and the disk from that one
instant. A guest that is writing files and dirtying memory restores with:

- every record it had fsynced, and at most the one record whose fsync was in
  flight, so the disk and the memory image come from the same instant;
- a filesystem that checks clean (`btrfs check --readonly` reports no error)
  and whose files all match the checksums the guest wrote beside them;
- a memory image that is one instant, not a copy smeared across the capture.

That is stronger than a crash-consistent disk copy, because memory is from the
same instant as the disk, and it is not application-consistent: a program
resumes exactly where it was, with whatever it had not yet flushed still in
its own buffers. The trace names the mechanism: `i9.snapshot.pause` with
`failed=false`, `i9.capture.quiesce` with `block=true`, and
`i9.capture.ring` showing `inflight=0` on the block queue
(`i9 trace search -t 'i9.capture.*' --session <pid> --internal`; `--internal` lists the spans
that the default view folds away).

**An interrupted capture never appears under its final name.** A capture is
written to `<name>.tmp.<pid>-…`, with a `.progress` file beside it, and renamed
to `wsnap-<time>-<n>.i9io` only after it is sealed. If the capturing process is
killed, `i9 vm save` exits 12 (EVMUNREACHABLE), no file has the final name, and
the session removes the partial `.tmp` and `.progress` files when it sees the
capturing process end. If only the `vm save` client is killed, the capture
still completes: the archive appears, validates and restores.

One check decides whether a file is a complete snapshot, and every reader
uses it: `i9 archive validate` exits 4 with `INCOMPLETE (unsealed)` for a
capture that was never sealed and `INCOMPLETE (truncated)` for a snapshot
with bytes missing, and `i9 vm rewind` refuses the same file with exit 4
(EVALIDATION) and the same reason (`… is not a complete snapshot — truncated: …`), leaving the
running VM untouched. An archive that is still being written, such as the
trace log, is reported as open rather than incomplete.

**A connection that drops during a download is retried.** An image or parent
served over HTTP that closes the connection for a few requests is fetched
again, and the guest's memory reads back byte for byte. A connection that never
recovers, or a response cut short of its length, ends in a bounded refusal
(exit 7, `refusing to cold-boot…`), not a hang, and leaves no VM behind.

**A delta whose parent is gone is refused by name.** A snapshot (`vm save`) or
parked archive (`vm stop`) of a VM that was started from a URL records that URL
as its `parent:` (`i9 archive info <file>`). It restores while the parent is
served. With the parent removed from the server it is refused at once; with
the server gone it is refused the same way. A warm
local cache does not stand in for the parent:

```
error: i9: RPC error: restore: parent <url>: remote archive is empty or unreachable: <url> (streaming restore of <path> failed (unclassified); refusing to cold-boot over an archive that may carry a checkpoint)
```

The trace shows the cause: `i9.lws_http.get` with `status_code=404`. A snapshot
of a VM started from a local image names no parent and restores with nothing
else, so a snapshot of a VM started from a URL is as durable as the object at
that URL.

**Keep the image available while a VM started from it runs.** A demand-paged
VM keeps fetching pages from its image. If the object behind it starts
answering 404, an `i9 vm exec` that needs a page not yet fetched exits 7 after
about 15 seconds without naming the object, `i9 vm ls` keeps showing the VM as
running. The trace records the
status as `i9.lws_http.get` with `status_code=404`.

**Rewind is a restore, not a replay.** `i9 vm rewind` puts the VM back in the
state of an earlier snapshot and the guest continues from that instant. What it
does next is not recorded and is not repeated deterministically.

## What the guest can reach on the host

A guest reaches the host through its default gateway, which `ip route` inside
the guest shows. A connect to the gateway lands on the host's loopback. The
host's own networks (loopback, LAN, VPN) are refused in every egress mode
unless a literal `--allow` names them, so `--allow 127.0.0.1:<port>` opens that
one host port to the guest, dialed at the gateway. Another port stays refused,
and `--egress allow` alone opens none. `localhost` is a name rather than an
address, so `--allow localhost:<port>` opens nothing and is refused at the
command line. Each such connect records an `i9.slirp.host_network` span naming
the address the guest dialed, where it landed on the host, the verdict, and the
literal rule that opened it or the literals that did not cover it.

## The guest's network

Every VM's network is the same: the guest is `192.168.86.20/24` and its gateway
is `192.168.86.1`, which is the host (a connect to it lands on the host's
loopback). A fork child has its parent's address, MAC address and hostname;
each VM has its own virtual network behind the host, so the identical
addresses do not conflict. `192.168.86.0/24` is also a common home-router
range. When the host's LAN uses it, a LAN machine at an address in that range
cannot be reached from the guest: the guest treats the whole `/24` as directly
attached, asks for the machine's MAC address there, and nothing answers (`ip
neigh` in the guest lists the entry as `INCOMPLETE`). The host itself reaches
its LAN as usual. No flag changes the guest's subnet.

## Resource footprint

These are measurements from evaluation runs, with their conditions, not
limits or guarantees. A default VM has a 2 GiB guest (`free -m` shows about
1920 MB on x86_64 and arm64 alike).

| What | Measured | Conditions |
|---|---|---|
| Host memory, idle VM | about 0.75 to 1.1 GB | Linux arm64 and macOS arm64, just booted |
| Host memory, VM under load | 2.3 to 3 GB, outliers to 5.1 GB | three or four VMs forked from one snapshot, a test suite running in each; macOS arm64 and Linux x86_64 |
| Host memory after a guest touches memory | 5.65 GB | one guest touched 1.8 GiB; the pages the guest later freed were not handed back while the VM ran |
| Host memory during `i9 vm rewind` | peak 19.1 GB | one measurement, 32 GiB macOS arm64 host |
| Host disk, guest writes | 62 GiB written took the host's free space from 142 GB to 77 GB | the space was returned when the VM was stopped, not when the guest deleted the file |
| Host disk, snapshot removal | 57 MB freed removing eight snapshots from about 12 GB | only chunks no other snapshot shares are freed |

Size the number of VMs against the host's free memory at the per-VM figures
above, and keep a guest's writes within the host's free disk: nothing refuses a
guest write because the host is nearly full. Stopping a VM returns its host
memory; a plain `i9 vm stop` also saves an archive of the VM, which takes disk
of its own, and `--discard` saves nothing.

## Related pages

- [Getting started](getting-started.md): start, use, and stop a VM.
- [How to start a VM](how-to-start-a-vm.md): each start mode in practice.
- [Routes reference](routes.md): every route, status, and header.
- [Installer reference](installer.md): modes, variables, files, and messages.
- [Manifest reference](manifest.md): the fields of the manifest.
