Agent VM environment and runtime

Agent VMs come pre-configured with development tools and Claude Code. You can customize the environment with custom baked images and repo hooks. This page explains what is available and how to extend it. For per-repo setup that runs after cloning, including dependency installs and code generation, see Repo Hooks.

Pre-installed tools

Every agent VM starts from a base image built on Debian 12 (Bookworm) with the following tools pre-installed:

Tool	Purpose
Git	Version control: cloning repos, creating branches, committing
Git LFS	Large-file support. The filters are installed system-wide and the hooks ship in Git’s init template, so every clone materializes LFS files on checkout and uploads new objects on push
Claude Code	The AI coding agent that runs on the VM (pinned standalone binary)
opencode	Agent backend for models served through an inference connection (pinned standalone binary)
Codex CLI	Alternative agent backend (pinned standalone binary and matching `codex-code-mode-host` execution companion, with `apply_patch` / `applypatch` structured-patch aliases)
gh	GitHub CLI: PR creation, issue management, CI checks
jq / yq	JSON and YAML processing
rg (ripgrep)	Fast recursive code search
curl, unzip, tmux	HTTP client, archive extraction, terminal sessions
bubblewrap	Filesystem sandbox used by the Codex CLI
cloud-init	Applies per-deployment boot configuration
sudo	The `murmur` agent user has passwordless sudo: agents can install system packages at runtime

Language runtimes (Go, Python, Node.js, Ruby, Rust, etc.) are not installed. They belong in a custom image baked from your recipe. The base image is maintained by the Murmur platform and updated regularly with security patches. Because agents have passwordless sudo, they can install missing packages at runtime with commands such as sudo apt-get install. On an image whose recipe adds Node.js, npx playwright install --with-deps chromium also works. Runtime installs add time to every spawn, so bake stable dependencies into a custom image. Organizations that want a non-root agent can remove /etc/sudoers.d/murmur in their recipe’s provisioning script. See Agent VM controls for why root on the VM is not an isolation boundary.

The base image provisioning script

The exact script that builds the base image, for reference when deciding what your recipe still needs to install:

provision.sh

#!/bin/bash
set -euo pipefail

# ── Keep PREINSTALLED.md and the public docs in sync ─────────────────
# This script and terraform/packer/scripts/PREINSTALLED.md must reflect
# each other. When you add or remove an install command below, mirror the
# change in PREINSTALLED.md — that file is read by terraform and shipped
# to the murmur catalog as the "What's on" summary that's surfaced in the
# Recipes UI and the Copy-for-LLM prompt template.
#
# This script is also published verbatim in the customer docs:
# prassoai/murmuration-docs configuration/vm-environment.mdx, under
# "The base image provisioning script". Whenever you change this file,
# update that page in the same change.
# ──────────────────────────────────────────────────────────────────────

# Provision the murmur base image (layer 1).
#
# This image ships everything murmur needs to run: OS packages, Node.js
# (Claude Code requirement), Claude Code, gh CLI, SSH known hosts,
# cloud-init, service user, and the systemd units.
#
# Language runtimes (Go, Python, etc.) belong in a customer image (layer 2)
# built on top of this base. See terraform/packer/customer-example/.
#
# Per-deployment config travels as cloud-init user data on both GCE and AWS.
# Cloud-init writes /etc/murmur/boot.sh which downloads binaries, writes
# config to disk, and starts murmur-boot.service.

export DEBIAN_FRONTEND=noninteractive

# ── System packages ──────────────────────────────────────────────────────────

apt-get update -qq
# Codex CLI uses bwrap (Debian: bubblewrap) for its default
# `workspace-write` sandbox on Linux — required for any codex-backend agent
# that executes shell commands.
apt-get install -y -qq git git-lfs jq ripgrep curl unzip tmux cloud-init bubblewrap sudo > /dev/null

# An EC2 instance built from this image obtains its first credential pair by
# signing a GetCallerIdentity request with SigV4 (DESIGN_VM_ATTESTED_BOOTSTRAP),
# and curl is what signs it. A curl without --aws-sigv4 produces a VM that boots,
# fails attestation, and crash-loops with nothing having complained — so the
# bake is where that is found out. (Added in curl 7.75; Debian 12 ships 7.88.)
if ! curl --help all | grep -q -- --aws-sigv4; then
  echo "FATAL: curl lacks --aws-sigv4; EC2 instances from this image cannot attest for credentials" >&2
  exit 1
fi

# ── Git LFS ──────────────────────────────────────────────────────────────────
# git-lfs needs two halves and they install in different places.
#
# The smudge/clean filters MATERIALIZE files. They are git config, so --system
# covers every repository at once; without them a clone of an LFS repository
# leaves pointer files on disk and the agent reads a hash where it expects the
# file. --skip-repo because the bake has no repository to install hooks into.
git lfs install --system --skip-repo

# The hooks carry everything the filters cannot: pre-push UPLOADS newly
# committed objects, and post-checkout/post-merge/post-commit fix up the
# working tree after a ref moves. They live in a repository's own hooks
# directory, and `git lfs install` can only write them into a repository that
# already exists — a plain `git clone` never adds them. Without pre-push a
# push publishes pointers whose blobs were never uploaded, leaving the remote
# branch referencing objects that do not exist.
#
# Git copies its init template into every repository it creates, so the hooks
# go there: workspace clones, plugin clones, and anything the agent clones
# itself all get them. The template is seeded from git's own so nothing it
# normally provides is lost, and the hooks are taken from git-lfs rather than
# written out here, so whichever set this git-lfs version installs is the set
# that ships.
GIT_TEMPLATE_DIR=/usr/local/share/git-core/murmur-templates
mkdir -p "${GIT_TEMPLATE_DIR}/hooks"
cp -r /usr/share/git-core/templates/. "${GIT_TEMPLATE_DIR}/"
LFS_HOOK_REPO="$(mktemp -d)"
git init -q "${LFS_HOOK_REPO}"
git -C "${LFS_HOOK_REPO}" lfs install --local
find "${LFS_HOOK_REPO}/.git/hooks" -maxdepth 1 -type f ! -name '*.sample' \
  -exec cp {} "${GIT_TEMPLATE_DIR}/hooks/" \;
rm -rf "${LFS_HOOK_REPO}"
git config --system init.templateDir "${GIT_TEMPLATE_DIR}"

# OpenSnitch is the pinned transparent network interception data plane. Only the
# daemon package is installed; the PyQt desktop UI is intentionally absent.
OPENSNITCH_VERSION=1.8.0-1
case "$(dpkg --print-architecture)" in
  amd64) OPENSNITCH_SHA256=9f517926877f07761ca95ec43dc9daefecac582574f9856079e1064be3fa1c8a ;;
  arm64) OPENSNITCH_SHA256=7d80a1f6649d7f132bf19f860823ce9df4bcc86d2a7547ec03381165f76dfb3a ;;
  armhf) OPENSNITCH_SHA256=c426df6106a2376c6c04f8394f7bef63f3fdf0d054f68481f7d0478d10aacf7a ;;
  *) echo "unsupported OpenSnitch architecture: $(dpkg --print-architecture)" >&2; exit 1 ;;
esac
OPENSNITCH_DEB="opensnitch_${OPENSNITCH_VERSION}_$(dpkg --print-architecture).deb"
curl -fsSLo "/tmp/${OPENSNITCH_DEB}" "https://github.com/evilsocket/opensnitch/releases/download/v1.8.0/${OPENSNITCH_DEB}"
echo "${OPENSNITCH_SHA256}  /tmp/${OPENSNITCH_DEB}" | sha256sum -c -

# The package post-install script starts opensnitch immediately. Starting and
# then stopping its nftables/NFQUEUE rules can sever Packer's active SSH
# connection. Debian's policy-rc.d contract suppresses service startup while
# preserving any policy supplied by the base image.
POLICY_RC_D=/usr/sbin/policy-rc.d
POLICY_RC_D_BACKUP_DIR=
if [ -e "$POLICY_RC_D" ]; then
  POLICY_RC_D_BACKUP_DIR=$(mktemp -d)
  mv "$POLICY_RC_D" "$POLICY_RC_D_BACKUP_DIR/policy-rc.d"
fi
restore_policy_rc_d() {
  rm -f "$POLICY_RC_D"
  if [ -n "$POLICY_RC_D_BACKUP_DIR" ]; then
    mv "$POLICY_RC_D_BACKUP_DIR/policy-rc.d" "$POLICY_RC_D"
    rmdir "$POLICY_RC_D_BACKUP_DIR"
  fi
}
trap restore_policy_rc_d EXIT
printf '#!/bin/sh\nexit 101\n' > "$POLICY_RC_D"
chmod 0755 "$POLICY_RC_D"
apt-get install -y -qq "/tmp/${OPENSNITCH_DEB}" > /dev/null
restore_policy_rc_d
trap - EXIT
rm "/tmp/${OPENSNITCH_DEB}"
systemctl disable opensnitch.service

# ── SSM Agent (optional, platform images only) ──────────────────────────────
# Enables `aws ssm start-session` for debugging without SSH keys or ingress
# rules. Only installed when INSTALL_SSM_AGENT=1 — customer base images must
# not include it (trust boundary: we don't get shell access to customer VMs).
#
# Distro split: Debian's AWS AMI ships no agent, so install the .deb. Ubuntu's
# AWS AMI preinstalls amazon-ssm-agent as a snap (AWS recommends snap-only on
# Ubuntu >= 18.04); a `dpkg -i` on top collides ("installed by snap, use snap")
# and, under `set -euo pipefail`, would abort the bake — so just enable the
# preinstalled snap unit instead.
if [ "${INSTALL_SSM_AGENT:-}" = "1" ]; then
  # shellcheck disable=SC1091  # /etc/os-release is provided by the base image
  . /etc/os-release
  if [ "${ID:-}" = "ubuntu" ]; then
    systemctl enable snap.amazon-ssm-agent.amazon-ssm-agent.service
  else
    SSM_DEB="amazon-ssm-agent.deb"
    SSM_ARCH="amd64"
    if [ "$(uname -m)" = "aarch64" ]; then SSM_ARCH="arm64"; fi
    curl -fsSLo "$SSM_DEB" "https://amazon-ssm-us-east-1.s3.us-east-1.amazonaws.com/latest/debian_${SSM_ARCH}/amazon-ssm-agent.deb"
    dpkg -i "$SSM_DEB"
    rm "$SSM_DEB"
    systemctl stop amazon-ssm-agent || true
    systemctl enable amazon-ssm-agent
  fi
fi

# ── GitHub CLI ───────────────────────────────────────────────────────────────

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
  | tee /etc/apt/sources.list.d/github-cli.list > /dev/null
apt-get update -qq
apt-get install -y -qq gh > /dev/null

# ── Claude Code ──────────────────────────────────────────────────────────────
# Direct binary download — pinned version, no npm, no auto-update.
# The baked image is immutable; auto-update is irrelevant.

CLAUDE_ARCH="linux-x64"
if [ "$(uname -m)" = "aarch64" ]; then CLAUDE_ARCH="linux-arm64"; fi
curl -fsSLo /usr/local/bin/claude "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION}/${CLAUDE_ARCH}/claude"
chmod +x /usr/local/bin/claude

# ── Codex CLI ────────────────────────────────────────────────────────────────
# Standalone binary from GitHub Releases — pinned version, no npm.

CODEX_ARCH="x86_64"
if [ "$(uname -m)" = "aarch64" ]; then CODEX_ARCH="aarch64"; fi
for CODEX_BINARY in codex codex-code-mode-host; do
  curl -fsSL "https://github.com/openai/codex/releases/download/${CODEX_VERSION}/${CODEX_BINARY}-${CODEX_ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /usr/local/bin
  mv "/usr/local/bin/${CODEX_BINARY}-${CODEX_ARCH}-unknown-linux-musl" "/usr/local/bin/${CODEX_BINARY}"
  chmod +x "/usr/local/bin/${CODEX_BINARY}"
done
/usr/local/bin/codex --version
/usr/local/bin/codex-code-mode-host --help > /dev/null
# Codex exposes its structured patch parser through argv0 aliases. Keep both
# documented spellings on PATH so agent shells can apply focused file edits.
#
# These track the BAKED codex deliberately, and are not re-pointed at a build
# installed on demand. Nothing in murmuration invokes either name: codex is
# always launched by explicit path (internal/codex.Run), the multi-file
# dependency it does have is resolved beside its own executable rather than
# through PATH, and the `apply_patch` a codex model uses is a freeform tool
# call of its own — its instructions tell the model never to reach for the
# `applypatch` spelling at all. They are a convenience for an interactive
# agent shell, so pointing them at a versioned install would buy nothing and
# would mean writing into /usr/local/bin, where a turn already in flight is
# running the file being replaced.
ln -sf /usr/local/bin/codex /usr/local/bin/apply_patch
ln -sf /usr/local/bin/codex /usr/local/bin/applypatch

# ── opencode CLI ─────────────────────────────────────────────────────────────
# Standalone binary from GitHub Releases — pinned version, no npm. The
# release tarball unpacks to a bare `opencode` binary.

OPENCODE_ARCH="x64"
if [ "$(uname -m)" = "aarch64" ]; then OPENCODE_ARCH="arm64"; fi
curl -fsSL "https://github.com/sst/opencode/releases/download/${OPENCODE_VERSION}/opencode-linux-${OPENCODE_ARCH}.tar.gz" | tar -xz -C /usr/local/bin
chmod +x /usr/local/bin/opencode

# ── Baked harness record ─────────────────────────────────────────────────────
# What this image pinned, declared by murmur.vm.v1.BakedHarnesses and read as
# protojson (internal/vmharness) — the same shape /etc/murmur/baked-image.json
# uses for the bake stamp beside it. The field names below are that message's;
# nothing else about this file is free-form.
#
# The versions are in the same identifiers murmur's harness manifest uses — both this script and `make harness-vendor` fetch from these very URLs
# parameterised by this very string, so "the baked build satisfies the selected
# version" is an exact string comparison and never a parse of `--version`
# output, whose shape is each vendor's to change.
#
# A turn whose selection names a version this image already carries runs the
# baked binary and downloads nothing (internal/vmharness). An image without
# this file simply installs on demand, which is why writing it is an
# optimisation rather than a contract.

mkdir -p /etc/murmur
cat > /etc/murmur/baked-harnesses.json <<EOF
{"dir":"/usr/local/bin","harnesses":{"claude":"${CLAUDE_CODE_VERSION}","codex":"${CODEX_VERSION}","opencode":"${OPENCODE_VERSION}"}}
EOF
chmod 0644 /etc/murmur/baked-harnesses.json

# ── yq (YAML parser for systemd boot script) ────────────────────────────────

YQ_VERSION="v4.52.4"
curl -fsSLo /usr/local/bin/yq "https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/yq_linux_amd64"
chmod +x /usr/local/bin/yq

# ── SSH known hosts ──────────────────────────────────────────────────────────

mkdir -p /etc/ssh
ssh-keyscan -t ed25519,rsa github.com >> /etc/ssh/ssh_known_hosts || { echo "WARNING: ssh-keyscan failed, GitHub SSH may not work" >&2; }

# ── SSH key-based auth ───────────────────────────────────────────────────────
# Developer isolation: the workflow's InstallSSHKeys activity writes each
# developer's GitHub SSH keys to ~murmur/.ssh/authorized_keys post-boot.
# OS Login is disabled (no enable-oslogin metadata) so these keys are the
# auth gate.

# Harden sshd: pubkey only, no password auth. Write a low-numbered drop-in
# instead of editing /etc/ssh/sshd_config directly. Both Debian 12 and Ubuntu
# 24.04 `Include /etc/ssh/sshd_config.d/*.conf` at the top of the main file,
# and sshd uses the first value seen for each keyword — so a main-file edit is
# overridden by any drop-in. Ubuntu cloud images ship 60-cloudimg-settings.conf;
# the 00- prefix sorts ahead of it so our hardening actually wins on both distros.
mkdir -p /etc/ssh/sshd_config.d
cat > /etc/ssh/sshd_config.d/00-murmur-hardening.conf << 'SSHD'
PasswordAuthentication no
PubkeyAuthentication yes
SSHD

# ── Service user ─────────────────────────────────────────────────────────────

useradd --create-home --shell /bin/bash murmur 2>/dev/null || true

# Phase 1 allows every connection while OpenSnitch records the decision. The
# first rule gives murmur traffic a stable rule identity; the final rule keeps
# all other queued traffic off the interactive AskRule path.
MURMUR_UID=$(id -u murmur)
install -d -m 0755 /etc/opensnitchd/rules
rm -f /etc/opensnitchd/rules/*.json
cat > /etc/opensnitchd/default-config.json <<'OPENSNITCH_CONFIG'
{
  "Server": {
    "Address": "unix:///run/murmur-network/opensnitch.sock",
    "Authentication": {"Type": "simple", "TLSOptions": {"CACert": "", "ServerCert": "", "ClientCert": "", "ClientKey": "", "SkipVerify": false, "ClientAuthType": "no-client-cert"}},
    "LogFile": "/var/log/opensnitchd.log"
  },
  "DefaultAction": "allow",
  "DefaultDuration": "once",
  "InterceptUnknown": true,
  "ProcMonitorMethod": "ebpf",
  "LogLevel": 2,
  "LogUTC": true,
  "LogMicro": true,
  "Firewall": "nftables",
  "FwOptions": {"ConfigPath": "/etc/opensnitchd/system-fw.json", "MonitorInterval": "15s", "QueueBypass": true},
  "Rules": {"Path": "/etc/opensnitchd/rules/", "EnableChecksums": false},
  "Ebpf": {"EventsWorkers": 8, "QueueEventsSize": 0},
  "Stats": {"MaxEvents": 1000, "MaxStats": 1000, "Workers": 6},
  "Internal": {"GCPercent": 100, "FlushConnsOnStart": false}
}
OPENSNITCH_CONFIG
cat > /etc/opensnitchd/rules/100-murmur-phase1-allow.json <<EOF
{"name":"murmur-phase1-allow","enabled":true,"precedence":true,"nolog":false,"action":"allow","duration":"always","operator":{"type":"simple","operand":"user.id","data":"${MURMUR_UID}","sensitive":false,"list":[]}}
EOF
cat > /etc/opensnitchd/rules/999-phase1-catchall-allow.json <<'EOF'
{"name":"phase1-catchall-allow","enabled":true,"precedence":false,"nolog":true,"action":"allow","duration":"always","operator":{"type":"simple","operand":"true","data":"","sensitive":false,"list":[]}}
EOF

# Passwordless sudo: the agent has root on its own VM by design. The VM is
# untrusted, ephemeral, and single-tenant, and all real isolation is enforced
# server-side (proxy admission, identity-scoped API, per-tenant KMS the VM
# never touches) — root lets agents self-provision system dependencies at
# runtime (browser libraries, compilers, ...). Customers who want a non-root
# agent can remove this drop-in in their own bake. See docs/TRUST_BOUNDARIES.md.
echo "murmur ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/murmur
chmod 0440 /etc/sudoers.d/murmur
visudo -cf /etc/sudoers.d/murmur

cat > /home/murmur/.bashrc << 'BASHRC'
[[ $- == *i* ]] || return
if tmux has-session -t claude 2>/dev/null; then
  echo "  tmux attach -t claude    — attach to Claude"
fi
echo "  tmux ls                  — list sessions"
echo ""
BASHRC
chown murmur:murmur /home/murmur/.bashrc

# Prep SSH directory for InstallSSHKeys to write authorized_keys post-boot.
install -d -m 0700 -o murmur -g murmur /home/murmur/.ssh

# ── System environment ───────────────────────────────────────────────────────
# Prepare the /etc/murmur directory for cloud-init to write config into.
mkdir -p /etc/murmur

# Stamp the base image with its bake time. Opaque debug info surfaced by the
# Identify activity so a running VM reveals how stale its base image is.
# chmod: written by root, read by the murmur worker.
date -u +%Y-%m-%dT%H:%M:%SZ > /etc/murmur/base-image-baked-at
chmod 0644 /etc/murmur/base-image-baked-at

# Stamp the base image with its capability version: which revision of this
# script built it. Monotonic — a higher version provisions everything a lower
# one does. Bump it in the same commit as the provisioning change that adds a
# capability something else gates on, and declare that capability in
# internal/basecap with the bumped value; the two are held equal by
# TestBaseImageCapabilityVersion in this directory. Identify reports the number
# so a feature can ask what the image under it provides — the murmur-vm binary
# version answers nothing about that.
BASE_IMAGE_CAPABILITY_VERSION=1
printf '%s\n' "${BASE_IMAGE_CAPABILITY_VERSION}" > /etc/murmur/base-image-capability-version
chmod 0644 /etc/murmur/base-image-capability-version

# No systemd services are installed here. Cloud-init user data writes the
# murmur-worker.service unit, enables it, and starts it on first boot.
# PrepareSnapshot deletes everything cloud-init wrote so baked images are
# clean. See internal/activityimpl/bootscript for the user data template.

Per-spawn setup

Murmur has no environment-level startup script: an environment is a pure compute shape (substrate, machine type, disk type, and disk size). Setup that must run on every spawn belongs in a repo hook, which runs after the repos are cloned and before the agent starts. Everything stable belongs in a custom image.

Custom images

For toolchains and system packages, bake a custom image instead of installing them on every spawn. Custom images use recipes and murmur bake to produce VM images with your toolchain pre-installed.

Recipes

A recipe defines how to build a custom image:

# Set via: murmur set recipe my-recipe
name: my-recipe
base_image_gce_ref: default  # Start from the platform base image
provisioning_script: |
  #!/bin/bash
  set -e
  
  # Install Go
  wget -q https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
  tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
  export PATH=$PATH:/usr/local/go/bin
  
  # Install Docker
  curl -fsSL https://get.docker.com | sh
  
  # Install CUDA toolkit (for GPU workloads)
  # apt-get install -y nvidia-cuda-toolkit
  
  # Pre-install project dependencies
  cd /tmp && git clone https://github.com/org/repo.git
  cd repo && go mod download
  rm -rf /tmp/repo
provisioning_timeout: 30m
secret_allowlist:
  - npm-token  # Secrets needed during image build

Baking an image

murmur bake my-recipe --environment default --placement us-central1 --service-profile infra-bot

This starts an image build process. You can monitor progress with:

murmur bakes ls

Once the bake completes, set the workspace’s image_ref to the resulting catalog image. The image is named <recipe>-<first 16 characters of the image hash> (with -<region> appended on AWS). List your images with murmur get image. Every VM the workspace launches then boots from it.

When the image is used

A VM that boots from a custom image already has all your tools installed, with no per-spawn install delay.

Identifying the image from inside a VM

Every image baked from a recipe records its own build at /etc/murmur/baked-image.json. The file is written during the bake, so every VM booted from that image reads the same values, and it is readable by any user on the VM. No sudo, no network, no Murmur CLI:

cat /etc/murmur/baked-image.json

{"recipe":"my-recipe","recipeGeneration":"1757000000000001","imageHash":"0f5e1c8a2b3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7","imageName":"murmur-3d7a91c4e2b05f68-0f5e1c8a2b3d4e5f","bakedAt":"2026-09-04T12:00:00Z"}

Field	Meaning
`recipe`	The recipe this image was baked from.
`recipeGeneration`	The version of that recipe record the bake read. Omitted for a Murmur-shipped built-in recipe, which has no stored version.
`imageHash`	Hash of everything that went into the bake: the base image, the provisioning script, the architecture, and the secret allowlist.
`imageName`	Name of the cloud image the bake produced: the GCE image, or the AMI on AWS.
`bakedAt`	When the bake ran, UTC.

Pull out one field with jq:

jq -r .recipe /etc/murmur/baked-image.json

The catalog image record for the same build is named <recipe>-<first 16 characters of imageHash>, with -<region> appended on AWS, so you can go from a running VM to the record it came from:

murmur get image my-recipe-0f5e1c8a2b3d4e5f

Every value describes the build and is fixed at bake time. The recipe may have been edited or deleted since, and the workspace may have been moved to a newer image. Under every recipe build sits the platform base image, which stamps two files of its own, so a VM booted from a recipe build has all three:

File	Contents
`/etc/murmur/base-image-baked-at`	When the platform base image was built, UTC, e.g. `2026-09-04T12:00:00Z`.
`/etc/murmur/base-image-capability-version`	A decimal integer, e.g. `1`, naming what that base image provisions. It is monotonic: a higher version provides everything a lower one does. Murmur reports it for every VM and uses it to decide whether a feature can run on the machine.

cat /etc/murmur/base-image-capability-version

Environment variables on VMs

Agent VMs have several environment variables available:

Variable	Description
`ANTHROPIC_MODEL`	The explicit or `murmur.yaml` model for this agent, when one is set (e.g. `claude-opus-4-8`). See Model Selection.
`GH_TOKEN`	GitHub token for repo operations (PR creation, cloning, API calls)
`MURMUR_WORKFLOW_ID`	The agent’s workflow identifier
`HOME`	Home directory for the agent user

Mounted secrets appear as their own environment variables, described below.

Secrets

Secrets are delivered as environment variables (or files) through secret mounts. A workspace declares them in runtime_secret_mounts; your own secrets are mounted with murmur secret mount; murmur spawn -e NAME forwards one variable for a single spawn. An environment mount uses the secret’s name as the variable name unless the mount sets env_name:

# In the workspace
runtime_secret_mounts:
  - name: NPM_TOKEN
    mount_type: MOUNT_TYPE_ENV

echo "$NPM_TOKEN"
# → your-secret-value

Secrets are decrypted from KMS in memory only. They are never written to disk. See Encryption for details on how secrets are protected.

Claude Code configuration

Murmur writes Claude Code’s ~/.claude/settings.json on the VM before each turn, merging into any existing file. It configures:

Fast mode: fastMode, on when the spawn asks for fast mode (fast_mode: true in .murmur/murmur.yaml sets the default)
Permissions: a permissions.allow list of pre-approved tools, such as murmur MCP tools and read-only gh pr commands
Hooks: a Stop hook that keeps the agent from finishing while checklist tasks are incomplete, and PreToolUse hooks that redirect interactive tools that cannot work unattended

The murmur MCP server is registered separately in ~/.claude.json. The model is not set in settings.json; it reaches Claude Code through ANTHROPIC_MODEL and the agent definition (see Model Selection). Agents should not modify settings.json directly. To customize Claude Code behavior, use murmur spawn --append-system-prompt or define an agent persona.

Repo hooks vs. baked images

Use this decision table to choose between a repo hook and a custom image:

Criteria	Repo hook	Custom image
Install time	Runs on every spawn (adds to startup latency, 5-minute budget)	Pre-installed (no boot delay)
Install size	Dependency installs, codegen, local config	Large toolchains (Go, Rust, Docker, CUDA)
Iteration speed	Commit the hook, the next spawn on that branch uses it	Requires a bake (minutes to build)
Scope	Per repo and per branch	Per workspace
Reproducibility	Depends on external package registries at spawn time	Fully baked, no external dependencies at boot

Rules of thumb

If the setup changes with the code (dependencies, codegen), use a repo hook.
If the install takes over 2 minutes, bake it into an image.
If you need GPU drivers or CUDA, always use a custom image: these installations are too large and slow to repeat on every spawn.
If a tool is needed rarely or unpredictably, skip both. Agents have passwordless sudo and can install it themselves when a task actually needs it.

You can combine both approaches: use a custom image for the heavy base (Go, Docker, etc.) and a repo hook for the per-branch remainder (dependency installs, config files).

Getting Started

Core Concepts

Guides

Agent VM environment and runtime

Pre-installed tools

The base image provisioning script

Per-spawn setup

Custom images

Recipes

Baking an image

When the image is used

Identifying the image from inside a VM

Environment variables on VMs

Secrets

Claude Code configuration

Repo hooks vs. baked images

Rules of thumb

​Pre-installed tools

​The base image provisioning script

​Per-spawn setup

​Custom images

​Recipes

​Baking an image

​When the image is used

​Identifying the image from inside a VM

​Environment variables on VMs

​Secrets

​Claude Code configuration

​Repo hooks vs. baked images

​Rules of thumb

Pre-installed tools

The base image provisioning script

Per-spawn setup

Custom images

Recipes

Baking an image

When the image is used

Identifying the image from inside a VM

Environment variables on VMs

Secrets

Claude Code configuration

Repo hooks vs. baked images

Rules of thumb