image

An image 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 references one image via its image_ref field. Images are typically produced by the bake process. When you bake a recipe, the platform executes it against a base image and writes the resulting image back to the catalog with provenance metadata. Baked images are immutable — you cannot update or delete them. You can also author 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 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. Set on platform-managed images.
`aws`	object	one of	AWS AMI source. See AWS source fields.
`gce`	object	one of	GCE image source. See GCE source fields.
`docker`	object	one of	Docker container source. See 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 is produced by a recipe bake. Cannot be set via `murmur set`.

AMIs are region-bound. A baked image has one entry in ami_ids — the region the bake ran in. If a workspace references this image and its placement targets a different region, spawn fails.

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 is produced by a 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 and records what produced them. It is set automatically by the bake process and cannot be set via murmur set.

Name	Type	Required	Description
`provenance.recipe_ref`	string	yes	Name of the recipe that produced this image.
`provenance.image_hash`	string	yes	SHA-256 hex hash of bake inputs. 64 characters. Immutable.

Examples

Hand-authored GCE image

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"

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

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

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 appear in the catalog after a successful bake. Their names are generated and they carry provenance metadata:

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

murmur get image

Reading a single image

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 cannot be updated or deleted. Bake a new image from the recipe instead.

Images — concept overview
Recipes — the provisioning template that produces baked images
Workspaces — the resource that references an image via image_ref
murmur set — CLI command for creating and updating catalog resources
murmur get — CLI command for reading catalog resources
murmur bake — bakes images from recipes

Getting Started

Core Concepts

Guides

Fields

AWS source fields

GCE source fields

Docker source fields

Provenance fields

Examples

Hand-authored GCE image

Hand-authored AWS image

Hand-authored Docker image

Baked image (generated by the platform)

Listing images

Reading a single image

Errors

​Fields

​AWS source fields

​GCE source fields

​Docker source fields

​Provenance fields

​Examples

​Hand-authored GCE image

​Hand-authored AWS image

​Hand-authored Docker image

​Baked image (generated by the platform)

​Listing images

​Reading a single image

​Errors

​Related

Fields

AWS source fields

GCE source fields

Docker source fields

Provenance fields

Examples

Hand-authored GCE image

Hand-authored AWS image

Hand-authored Docker image

Baked image (generated by the platform)

Listing images

Reading a single image

Errors

Related