# Routes reference

The HTTP routes that `https://i9.io` serves for the agent-dev VM (the pages
under `/vm` and the supporting routes), and the asset host `https://a.i9.io`.

For the script these routes deliver, see [Installer reference](installer.md).
For the reasoning behind the negotiation, see
[How the /vm surface works](architecture.md).

## Page routes

Page routes answer `GET`. A `HEAD` request gets the status and headers of the
same `GET`, with no body.

| Route | Response |
|-------|----------|
| `/vm` | The installer script, the landing page, or the landing Markdown. See Negotiation on /vm below |
| `/vm/install.sh` | The installer script, for every `Accept` value |
| `/vm/AGENTS.md` | The agent instructions. See Negotiation on /vm/AGENTS.md below |
| `/vm/agent.md` | `301` redirect to `https://i9.io/vm/AGENTS.md` |
| `/vm/install.ps1` | The Windows PowerShell installer, as `text/plain; charset=utf-8` |
| `/vm/releases` | Every release, each with its platform binaries, their sizes and SHA-256 values. See Negotiation on /vm/releases below |
| `/vm/download` | `301` redirect to `https://i9.io/vm/releases` |
| `/vm/copy/<id>` | `204` with no body: the landing page's copy button reporting a copied command. `<id>` is one of the page's known copy ids, and the count names it |
| `/vm/fonts/<name>.woff2` | A site font, as `font/woff2`; `/vm/fonts/<name>.OFL.txt` is its licence, as `text/plain; charset=utf-8` |
| `/favicon.ico`, `/favicon.svg`, `/apple-touch-icon.png`, `/vm/og.png` | The site icons and the link-preview image |
| `/agent.md` | `301` redirect to `https://i9.io/vm/AGENTS.md` |
| `/terms` | The Terms of Service, as Markdown or HTML by `Accept` |
| `/privacy` | The privacy policy, as Markdown or HTML by `Accept` |
| `/vm/pricing` | What the free tier limits, what a grant is, and how to get one: the grant packs and prices, or how to request a grant while grants are not sold online. Markdown or HTML by `Accept` |
| `/vm/verify` | How to verify a release: the release key and the stable release tag, as Markdown or HTML by `Accept` |
| `/vm/security` | The security page, as Markdown or HTML by `Accept` |
| `/vm/contact` | The contact page, as Markdown or HTML by `Accept` |
| `/vm/release-signing.pub` | The current release signing public key, as `application/x-pem-file`. `404` until a key is enrolled |
| `/.well-known/security.txt` | The security contact file, as `text/plain; charset=utf-8` |
| `/robots.txt` | The crawler rules, as `text/plain; charset=utf-8`: every crawler allowed, every content signal granted, and the sitemap named. Served on `i9.io` only |
| `/sitemap.xml` | The pages of `i9.io` for a search engine to index: the landing, the agent instructions, the releases, the site pages and each published document, as `application/xml; charset=utf-8`. Served on `i9.io` only |
| `/llms.txt` | An index of the site for agents, as `text/markdown; charset=utf-8`: the agent instructions, each published document, and every other page in the sitemap. Served on `i9.io` only |
| `/vm/docs` | An index of the published documents, as Markdown or HTML by `Accept` |
| A document name under `/vm/docs` | That published document, as Markdown or HTML by `Accept`. Names are lowercase. An unknown name is `404` with a body that names the path |
| `/version` | The commit of the deployed site as `text/plain`, or `unknown`. `Cache-Control: no-store` |
| `/` | `302` to the product entry (`/vm` today); a `404` with a body when there is not exactly one |

A legal text that still carries a draft marker is never served: the route
answers `503` with `Cache-Control: no-store` until the text is final
(today none is).

### Negotiation on /vm

The first matching row decides the response. Every response carries
`Vary: Accept, User-Agent`.

| `Accept` header | Body | `Content-Type` |
|-----------------|------|----------------|
| Contains `text/markdown` | The landing page as Markdown | `text/markdown; charset=utf-8` |
| Contains `text/html`, or the user agent is a link-preview crawler (Slack, X, Discord, Telegram, WhatsApp, Applebot and friends — they send no `text/html` but build a card from the page) | The landing page as HTML, with no script | `text/html; charset=utf-8` |
| Anything else, including `*/*` and no header | The installer script | `text/x-shellscript; charset=utf-8` |

### Negotiation on /vm/AGENTS.md

| `Accept` header | Body | `Content-Type` |
|-----------------|------|----------------|
| Contains `text/html` | The instructions rendered as HTML, with a `rel="alternate"` link to the Markdown | `text/html; charset=utf-8` |
| Anything else | The instructions as Markdown | `text/markdown; charset=utf-8` |

The Markdown body is identical to the comment block at the top of the
installer script.

### Negotiation on /vm/releases

Every response carries `Vary: Accept`.

| `Accept` header | Body | `Content-Type` |
|-----------------|------|----------------|
| Contains `text/html` | The page as HTML | `text/html; charset=utf-8` |
| Anything else | The page as Markdown | `text/markdown; charset=utf-8` |

The page lists, in this order: the current release (the one the stable VM
image for each architecture names, which the installer installs), the
newest build of main when it has not been promoted to stable, and every
earlier stable release, newest promotion first. The stable releases are
exactly the tags in `https://a.i9.io/i9/stable/index.json`, which each
promotion to stable appends to. A release the index does not list is not on
the page, even when it is the current release.

Each release's size and SHA-256 values come from its `release.json`, shown
only after its signature verifies with the release keys the installer
trusts. A release whose signature does not verify is not listed. A release
with a signed withdrawal is not listed, and the page states how many were
left out. When the bucket cannot be read, the route answers `503` with
`Cache-Control: no-store` rather than a shorter list.

### Paths that are not served

| Request | Response |
|---------|----------|
| An unknown path under `/vm` | `404`, `text/plain; charset=utf-8`, with a body that names the path |
| An unknown top-level path | `404`, `text/plain; charset=utf-8`, with a body that names the path |

The response for an unknown path does not depend on the `Accept` header.

## Request counting

The service counts successful `GET` requests for these steps. A `HEAD`
request is not counted.

| Step | Request |
|------|---------|
| Landing page | `/vm` answered as HTML or Markdown |
| Installer | `/vm` answered as the script, or `/vm/install.sh` |
| Windows installer | `/vm/install.ps1` |
| Agent instructions | `/vm/AGENTS.md` |
| Releases page | `/vm/releases` |
| Copy | `/vm/copy/<id>` answered `204`, the landing page's copy button |
| Binary download | One of the four platform binaries under `https://a.i9.io/i9/TAG/`, requested from its first byte. A `.sha256` sidecar is not counted |
| Manifest | `https://a.i9.io/vm/manifest.json` |
| Image restore | A VM image under `https://a.i9.io/vm/`, requested by an i9 binary that sends the telemetry beacon |

A count holds the funnel step, the public asset, and the operating
system, CPU architecture and i9 version the request carried — no IP
address, no location and no identifier. Turn the beacon off with
`i9 config set telemetry.enabled false`, or for a single run by setting
`DO_NOT_TRACK=1`.

## Asset host

`https://a.i9.io/KEY` serves the stored object named `KEY`. It answers `GET`
and `HEAD`, and serves nothing else: no page and no redirect. A key with a
leading `a/` segment names the same object as the path without it — a legacy
alias some older i9 binaries still request when they update.

| Property | Value |
|----------|-------|
| Range requests | `bytes=A-B`, `bytes=N-`, and `bytes=-N`. A range response is `206` with `Content-Range`. Multiple ranges in one request (`bytes=a-b,c-d,…`, up to 128 ranges and 16 MiB total, via the `x-i9-multirange` header) are answered with one `multipart/byteranges` body, never a whole-object `200` |
| `Accept-Ranges` | `bytes` on every success response; a `404` or `416` carries none |
| Missing object | `404` |
| `HEAD` | `200` with `Content-Length`, no body |

### Assets the /vm pages use

| Key | Object |
|-----|--------|
| `vm/manifest.json` | The manifest. See [Manifest reference](manifest.md) |
| `vm/agent-dev-ARCH-VERSION.boot.i9io` | A VM image for one architecture and version |
| `i9/TAG/i9-linux-x86_64` | The i9 binary of release `TAG` for Linux x86_64 |
| `i9/TAG/i9-linux-arm64` | The i9 binary of release `TAG` for Linux arm64 |
| `i9/TAG/i9-darwin-arm64` | The i9 binary of release `TAG` for Apple silicon macOS |
| `i9/TAG/i9-windows-x86_64.exe` | The i9 binary of release `TAG` for Windows x86_64 |
| `i9/TAG/release.json` | The sha256 and size of each binary of release `TAG`. The installer installs a binary only when its sha256 equals the one in this file |
| `i9/TAG/release.json.sig` | The release key's signature over the exact bytes of `release.json` |
| `i9/TAG/release.json.sigstore.json` | The Sigstore bundle for `release.json`. See `https://i9.io/vm/verify` |
| `i9/TAG/withdrawn.json` | Present when release `TAG` is withdrawn, with a signature in `withdrawn.json.sig`. The installer refuses a withdrawn release |
| `i9/TAG/NAME.sha256` | The SHA-256 sidecar of the binary `NAME` |
| `i9/latest/release.json` | Its `tag` names the release the `edge` channel installs |
| `i9/latest/NAME` and `i9/latest/NAME.sha256` | The newest build of the binary `NAME`, and its sidecar |

### Cache-Control

| Key | `Cache-Control` |
|-----|-----------------|
| A versioned image file ending in `.boot.i9io` | `public, max-age=31536000, immutable` |
| A key under `i9/TAG/` where `TAG` is not `latest` | `public, max-age=31536000, immutable` |
| A key under a content-addressed directory (a hash first segment, e.g. the GPL source tars) | `public, max-age=31536000, immutable` |
| Every other key, including `vm/manifest.json` and `i9/latest/` | `public, no-cache` |

### The x-i9-edge-cache header

Every asset response carries `x-i9-edge-cache`, which reports how the edge
cache served the bytes.

| Value | Meaning |
|-------|---------|
| `hit` | Every chunk of the range came from the edge cache |
| `miss` | Every chunk came from storage and entered the cache |
| `partial` | Some chunks came from the cache and some from storage |
| `bypass` | The chunk cache did not serve the request |

The chunk cache serves bounded `bytes=A-B` ranges of immutable objects in
2 MiB chunks, up to 16 chunks per request. Every other request is `bypass`.
A bounded range on an immutable object that starts at or past the object's
size is `416` with `Content-Range: bytes */SIZE`.
