Skip to main content

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.

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 run murmur bake, the platform executes a recipe 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

NameTypeRequiredDescription
namestringyesUnique identifier. DNS label format: [a-z][a-z0-9-]{0,62}. For baked images the name is generated automatically.
descriptionstringnoHuman-readable description shown in the dashboard. Maximum 1024 bytes.
architecturestringyesCPU architecture. Values: ARCHITECTURE_AMD64, ARCHITECTURE_ARM64.
preinstalledstringnoSummary of preinstalled software on this image. Set on platform-managed images.
awsobjectone ofAWS AMI source. See AWS source fields.
gceobjectone ofGCE image source. See GCE source fields.
dockerobjectone ofDocker 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:
NameTypeRequiredDescription
aws.ami_idsmap<string, string>yesRegion-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.provenanceobjectnoBake 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:
NameTypeRequiredDescription
gce.self_linkstringyesGCE image self-link. Format: projects/<project>/global/images/<name> or projects/<project>/global/images/family/<family>.
gce.provenanceobjectnoBake 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:
NameTypeRequiredDescription
docker.image_refstringyesOCI image reference (e.g. ghcr.io/foo/bar:v1.2).
docker.pull_credential_secretstringnoName of a tenant secret used for container registry authentication.
docker.provenanceobjectnoBake 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.
NameTypeRequiredDescription
provenance.recipe_refstringyesName of the recipe that produced this image.
provenance.image_hashstringyesSHA-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 murmur 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

CodeMeaningWhat to do
INVALID_ARGUMENTname is requiredProvide a name field.
INVALID_ARGUMENTname must match [a-z][a-z0-9-]{0,62}Use a valid DNS label for the name.
INVALID_ARGUMENTdescription exceeds 1024 byte limitShorten the description to 1024 bytes or fewer.
INVALID_ARGUMENTarchitecture is requiredSet architecture to ARCHITECTURE_AMD64 or ARCHITECTURE_ARM64.
INVALID_ARGUMENTunknown architecture valueUse a valid architecture enum value.
INVALID_ARGUMENTsource is required (aws, gce, or docker)Provide exactly one of aws, gce, or docker.
INVALID_ARGUMENTaws.ami_ids must be non-emptyAdd at least one region-to-AMI entry in aws.ami_ids.
INVALID_ARGUMENTaws.ami_ids: region key must be non-emptyEvery key in aws.ami_ids must be a non-empty region string.
INVALID_ARGUMENTaws.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_ARGUMENTgce.self_link is requiredProvide a gce.self_link value.
INVALID_ARGUMENTgce.self_link: invalid GCE image referenceUse the format projects/<project>/global/images/<name> or projects/<project>/global/images/family/<family>.
INVALID_ARGUMENTdocker.image_ref is requiredProvide a docker.image_ref value.
INVALID_ARGUMENTprovenance cannot be set via SetResourceProvenance is set by the bake process. Remove the provenance field from your input.
FAILED_PRECONDITIONbaked images are immutableBaked images cannot be updated or deleted. Bake a new image from the recipe instead.