> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# image

> Catalog resource that points to a runnable artifact on a substrate — an AWS AMI, GCE disk image, or Docker container reference for agent VMs.

An [image](/concepts/images) is a catalog resource that points to a runnable artifact on a specific substrate — an AWS AMI, a GCE disk image, or a Docker container. Each [workspace](/concepts/workspaces) references one [image](/concepts/images) via its `image_ref` field.

[Images](/concepts/images) are typically produced by the bake process. When you run `murmur bake`, the platform executes a [recipe](/concepts/recipe) against a base [image](/concepts/images) and writes the resulting [image](/concepts/images) back to the catalog with provenance metadata. Baked [images](/concepts/images) are immutable — you cannot update or delete them. You can also author [images](/concepts/images) manually to reference existing AMIs, GCE images, or Docker containers that you manage outside Murmur.

## Fields

| Name           | Type   | Required | Description                                                                                                                            |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string | yes      | Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`. For baked [images](/concepts/images) the name is generated automatically. |
| `description`  | string | no       | Human-readable description shown in the dashboard. Maximum 1024 bytes.                                                                 |
| `architecture` | string | yes      | CPU architecture. Values: `ARCHITECTURE_AMD64`, `ARCHITECTURE_ARM64`.                                                                  |
| `preinstalled` | string | no       | Summary of preinstalled software on this [image](/concepts/images). Set on platform-managed [images](/concepts/images).                |
| `aws`          | object | one of   | AWS AMI source. See [AWS source fields](#aws-source-fields).                                                                           |
| `gce`          | object | one of   | GCE image source. See [GCE source fields](#gce-source-fields).                                                                         |
| `docker`       | object | one of   | Docker container source. See [Docker source fields](#docker-source-fields).                                                            |

Exactly one of `aws`, `gce`, or `docker` must be set.

## AWS source fields

Set `aws` to reference one or more AMIs:

| Name             | Type                 | Required | Description                                                                                                                                               |
| ---------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aws.ami_ids`    | map\<string, string> | yes      | Region-to-AMI-ID map. Each key is an AWS region (e.g. `us-east-1`), each value is an AMI ID (e.g. `ami-0abc123def456789a`). Must have at least one entry. |
| `aws.provenance` | object               | no       | Bake provenance. Set automatically when the [image](/concepts/images) is produced by a [recipe](/concepts/recipe) bake. Cannot be set via `murmur set`.   |

<Note>
  AMIs are region-bound. A baked [image](/concepts/images) has one entry in `ami_ids` — the region the bake ran in. If a [workspace](/concepts/workspaces) references this [image](/concepts/images) and its [placement](/concepts/placement) targets a different region, spawn fails.
</Note>

## GCE source fields

Set `gce` to reference a GCE disk image or image family:

| Name             | Type   | Required | Description                                                                                                                                             |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gce.self_link`  | string | yes      | GCE image self-link. Format: `projects/<project>/global/images/<name>` or `projects/<project>/global/images/family/<family>`.                           |
| `gce.provenance` | object | no       | Bake provenance. Set automatically when the [image](/concepts/images) is produced by a [recipe](/concepts/recipe) bake. Cannot be set via `murmur set`. |

## Docker source fields

Set `docker` to reference a container image:

| Name                            | Type   | Required | Description                                                                    |
| ------------------------------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `docker.image_ref`              | string | yes      | OCI image reference (e.g. `ghcr.io/foo/bar:v1.2`).                             |
| `docker.pull_credential_secret` | string | no       | Name of a tenant secret used for container registry authentication.            |
| `docker.provenance`             | object | no       | Bake provenance. Reserved for container bakes. Cannot be set via `murmur set`. |

## Provenance fields

Provenance is present on baked [images](/concepts/images) and records what produced them. It is set automatically by the bake process and cannot be set via [`murmur set`](/cli/set).

| Name                    | Type   | Required | Description                                                                          |
| ----------------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| `provenance.recipe_ref` | string | yes      | Name of the [recipe](/concepts/recipe) that produced this [image](/concepts/images). |
| `provenance.image_hash` | string | yes      | SHA-256 hex hash of bake inputs. 64 characters. Immutable.                           |

## Examples

### Hand-authored GCE image

```yaml theme={null}
name: debian12-base
description: "Stock Debian 12 with our internal SDK"
architecture: ARCHITECTURE_AMD64
gce:
  self_link: "projects/acme-agents/global/images/family/debian-12-sdk"
```

```bash theme={null}
cat <<'EOF' | murmur set image debian12-base
name: debian12-base
description: "Stock Debian 12 with our internal SDK"
architecture: ARCHITECTURE_AMD64
gce:
  self_link: "projects/acme-agents/global/images/family/debian-12-sdk"
EOF
```

### Hand-authored AWS image

```yaml theme={null}
name: ubuntu22-ml
description: "Ubuntu 22.04 with CUDA and PyTorch"
architecture: ARCHITECTURE_AMD64
aws:
  ami_ids:
    us-east-1: "ami-0abc123def456789a"
    us-west-2: "ami-0def456789abc1234"
```

### Hand-authored Docker image

```yaml theme={null}
name: node20-dev
description: "Node.js 20 development container"
architecture: ARCHITECTURE_AMD64
docker:
  image_ref: "ghcr.io/acme/node20-dev:latest"
```

### Baked image (generated by the platform)

Baked [images](/concepts/images) appear in the catalog after a successful [`murmur bake`](/cli/bake). Their names are generated and they carry provenance metadata:

```yaml theme={null}
name: go-python-a1b2c3d4e5f67890
architecture: ARCHITECTURE_AMD64
gce:
  self_link: "projects/acme-agents/global/images/go-python-a1b2c3d4e5f67890"
  provenance:
    recipe_ref: go-python
    image_hash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
```

### Listing images

```bash theme={null}
murmur get image
```

### Reading a single image

```bash theme={null}
murmur get image debian12-base
```

## Errors

| Code                  | Meaning                                                | What to do                                                                                                                                       |
| --------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `INVALID_ARGUMENT`    | `name is required`                                     | Provide a `name` field.                                                                                                                          |
| `INVALID_ARGUMENT`    | `name must match [a-z][a-z0-9-]{0,62}`                 | Use a valid DNS label for the name.                                                                                                              |
| `INVALID_ARGUMENT`    | `description exceeds 1024 byte limit`                  | Shorten the `description` to 1024 bytes or fewer.                                                                                                |
| `INVALID_ARGUMENT`    | `architecture is required`                             | Set `architecture` to `ARCHITECTURE_AMD64` or `ARCHITECTURE_ARM64`.                                                                              |
| `INVALID_ARGUMENT`    | `unknown architecture value`                           | Use a valid architecture enum value.                                                                                                             |
| `INVALID_ARGUMENT`    | `source is required (aws, gce, or docker)`             | Provide exactly one of `aws`, `gce`, or `docker`.                                                                                                |
| `INVALID_ARGUMENT`    | `aws.ami_ids must be non-empty`                        | Add at least one region-to-AMI entry in `aws.ami_ids`.                                                                                           |
| `INVALID_ARGUMENT`    | `aws.ami_ids: region key must be non-empty`            | Every key in `aws.ami_ids` must be a non-empty region string.                                                                                    |
| `INVALID_ARGUMENT`    | `aws.ami_ids[<region>]: must match ami-[0-9a-f]{8,17}` | Each AMI ID must be a valid AWS AMI identifier (e.g. `ami-0abc123def456789a`).                                                                   |
| `INVALID_ARGUMENT`    | `gce.self_link is required`                            | Provide a `gce.self_link` value.                                                                                                                 |
| `INVALID_ARGUMENT`    | `gce.self_link: invalid GCE image reference`           | Use the format `projects/<project>/global/images/<name>` or `projects/<project>/global/images/family/<family>`.                                  |
| `INVALID_ARGUMENT`    | `docker.image_ref is required`                         | Provide a `docker.image_ref` value.                                                                                                              |
| `INVALID_ARGUMENT`    | `provenance cannot be set via SetResource`             | Provenance is set by the bake process. Remove the `provenance` field from your input.                                                            |
| `FAILED_PRECONDITION` | `baked images are immutable`                           | Baked [images](/concepts/images) cannot be updated or deleted. Bake a new [image](/concepts/images) from the [recipe](/concepts/recipe) instead. |

## Related

* [Images](/concepts/images) — concept overview
* [Recipes](/concepts/recipe) — the provisioning template that produces baked [images](/concepts/images)
* [Workspaces](/concepts/workspaces) — the resource that references an [image](/concepts/images) via `image_ref`
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources
* [`murmur bake`](/cli/bake) — CLI command for baking [images](/concepts/images) from [recipes](/concepts/recipe)