Skip to main content
A recipe defines how to build a custom VM image for your agents. It pairs a base image with a provisioning script that installs your toolchain: languages, package managers, SDKs, and build tools. When you bake it, the platform creates a scratch VM from the base image, runs your provisioning script, and snapshots the result as a new image. Agents boot from this image, so everything your script installs is available immediately. No install step at spawn time.

​
Base images

Every recipe starts from a platform base image that includes Debian 12, Git, Node.js, Claude Code, Codex CLI, and the gh CLI. Your provisioning script adds everything else. Agents run as the murmur user with passwordless sudo, so they can install a missing system package at runtime. A recipe avoids repeating that install on every spawn by including it in the bake. Organizations that want a non-root agent can remove /etc/sudoers.d/murmur in their provisioning script.

​
Provisioning script

The script runs as root on the scratch VM during the bake. It installs your toolchain and exits. Anything you install ends up in the final image.

​
Secret allowlist

If your provisioning script needs credentials, for example to install packages from a private registry, list the secret names in secret_allowlist. Only listed secrets are available during the bake.

​
Baking

This triggers a bake workflow that creates the image. The resulting image is bound to the placement: a GCE image lives in the placement’s GCP project, an AMI lives in the placement’s AWS account. See the custom images guide for a full walkthrough.

​
Automatic recipe updates

An agent can install a missing tool at runtime, but later agents would repeat the same work. Put durable fixes in the recipe. Murmur includes a service that turns an image-defect report, such as a missing tool, unavailable command, or outdated package, into the smallest recipe change that addresses it. The service rebuilds the image, boots it on a real VM to confirm the fix, and then updates the workspace. If verification does not pass, the service rejects the rollout and restores your recipe. It only acts on a report naming a concrete, durable defect: a tool absent, broken, or outdated. Platform bugs, missing permissions, and task-specific complaints are ignored, because no recipe change fixes them. Every step is a change-request, so the trail is permanent and reviewable after the fact: what changed in your recipe, why (the agent’s report, quoted), and which image each workspace moved to.

​
Choosing what the service may do

Each workspace decides what the service may do there with its Configure environment setting, under Access on the workspace’s settings page: The setting is an ordinary workspace grant to the service-profile:murmur-image-updater service profile, using role murmur-image-updater-propose or murmur-image-updater-autonomous with extendToRuntimeAgents set. You can also edit it in the workspace’s grants with murmur get workspace and murmur set workspace. The service’s authority covers only that workspace: the resources named under it, and the tenant’s shared recipes, images, and environments that the workspace may use (builtins, and any whose workspace use admits the workspace), which it can read but not change. Outside it, the service can only propose and endorse change requests and start itself under a service account a placement binds. The workspace creation defaults suggest Automatic. A change applies to the service’s next action in that workspace, including a run already in progress, with no restart. Work it has already started, such as a bake, finishes; anything after that follows the new setting. With Propose changes, the service opens two change-requests per defect: one for the recipe fix and one for the bake that rebuilds the image. Its report gives the approval order. Approve the recipe first, then the bake, and smoke-test the resulting image before approving the rollout. To turn the service off entirely, disable the flight with murmur rm flight murmur-configure-environment. Re-enable it with murmur set flight murmur-configure-environment.