# Manifest reference

The JSON document at `https://a.i9.io/vm/manifest.json`, which names the
agent-dev VM image for each architecture.

For how the installer gets its release data from it, see
[Installer reference](installer.md). For
why the manifest and the images cache differently, see
[How the /vm surface works](architecture.md#a-small-pointer-and-large-immutable-images).

## Response

| Header | Value |
|--------|-------|
| `Content-Type` | `application/json` |
| `Cache-Control` | `public, no-cache` |

## Top-level fields

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | The image name, `agent-dev` |
| `description` | string | A one-paragraph description of the image |
| `run_mode` | string | `shell` |
| `version` | string | The version of the most recently published image |
| `images` | object | One image entry per architecture, keyed by `x86_64` or `arm64`. See Image entry below |

## Image entry

| Field | Type | Description |
|-------|------|-------------|
| `url` | string | The address of the image file. The file name carries the architecture and the version |
| `blake3` | string | The BLAKE3 hash of the image file, in hexadecimal |
| `size` | integer | The size of the image file in bytes |
| `boot` | string | How the image starts. See Boot values below |
| `version` | string | The release this architecture's image was published from. The release is also the version in the image file name. The `stable` installer and `i9 update` install the `i9` binary of this release, so the host and the image match. The `edge` channel installs a newer binary beside this image, so a binary stamp newer than the image stamp is the paired state, not build skew |
| `format` | integer | The snapshot format generation the image was written in. `i9 run` compares it with the generation it reads before it fetches any of the image. An image of a newer generation is refused with exit 6 (`EREFUSED`), and the hint names `i9 update`. An `i9` older than the image still runs it when both read the same generation. An entry with no `format` is not compared |

The server parses the document as JSON and reads `images.x86_64` and
`images.arm64`. It takes an entry's release and image from the file name in
`url`, which has the form `agent-dev-ARCH-VERSION.boot.i9io`; an entry whose
file name has another form is skipped.

## Boot values

| Value | Meaning |
|-------|---------|
| `"checkpoint"` | The image carries a sealed checkpoint, and the VM resumes from it |
| `"cold"` | The image carries no checkpoint, and the guest runs its own boot sequence |

An entry with no `boot` field is treated as `"cold"`. Both kinds of image are
read over HTTP Range requests.

## Example

The `description` value is shortened here. `<version>` stands for a release version, `YYYY.MM.DD.HHMMSS-<sha9>`, and `<64 hex digits>` for a BLAKE3 digest. `<bytes>` stands for the image size in bytes, which changes with every release; replace the placeholders before using the example as JSON.

```json
{
  "name": "agent-dev",
  "description": "...",
  "run_mode": "shell",
  "version": "<version>",
  "images": {
    "arm64": {"blake3": "<64 hex digits>", "boot": "checkpoint", "format": 2, "size": <bytes>, "url": "https://a.i9.io/vm/agent-dev-arm64-<version>.boot.i9io", "version": "<version>"},
    "x86_64": {"blake3": "<64 hex digits>", "boot": "checkpoint", "format": 2, "size": <bytes>, "url": "https://a.i9.io/vm/agent-dev-x86_64-<version>.boot.i9io", "version": "<version>"}
  }
}
```

## Single-image form

A manifest with no `images` field and a top-level `url` describes one arm64
image. The server reads no top-level `url`: with no `images` entry for an
architecture, the installer for that architecture exits 8 (`EPLATFORM`) with
`the VM image is not published for`.

## Readers

| Reader | Fields read |
|--------|-------------|
| The server that renders the installer | `url` of `images.x86_64` and `images.arm64`. For the `stable` channel, the release in the file name is the release the installer installs, and the image is `https://a.i9.io/vm/FILENAME`. The signed `release.json` of that release supplies the binary's digest |
| `i9 run` with the manifest URL as its target | `url` and `format` of the entry for the host's architecture |

The shell installer and the Windows installer read no manifest themselves. The
release data the server writes into each script names the release, the binary
digest, and the image.

The `edge` channel installs the release named by
`https://a.i9.io/i9/latest/release.json`. Its VM image is the stable image of
the same architecture when that image's release is not newer than the edge
release, and none otherwise.

For `i9 run` with a manifest URL, see the [CLI reference](cli.md#i9-run).
