Agent VM environment and runtime

Agent VMs come pre-configured with development tools and Claude Code. You can customize the environment with startup scripts or custom baked images. This page explains what is available out of the box and how to extend it. For per-repo setup that runs after cloning — dependency installs, 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)
Codex CLI	Alternative agent backend (pinned standalone binary, 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, anything missing can be installed at runtime — sudo apt-get install just works, and on an image whose recipe adds Node.js, so does npx playwright install --with-deps chromium. Runtime installs cost time on every spawn, though: bake anything stable into a custom image. Orgs 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 isn’t 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

# ── 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}"

# ── 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
curl -fsSL "https://github.com/openai/codex/releases/download/${CODEX_VERSION}/codex-${CODEX_ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /usr/local/bin
# Rename the extracted binary to the expected name
mv "/usr/local/bin/codex-${CODEX_ARCH}-unknown-linux-musl" /usr/local/bin/codex
chmod +x /usr/local/bin/codex
# Codex exposes its structured patch parser through argv0 aliases. Keep both
# documented spellings on PATH so agent shells can apply focused file edits.
ln -sf /usr/local/bin/codex /usr/local/bin/apply_patch
ln -sf /usr/local/bin/codex /usr/local/bin/applypatch

# ── 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

# 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

# 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.

Startup scripts

Startup scripts run before the agent session starts, making them the right place for environment customization that needs to happen on every boot. Configure a startup script in your environment resource:

# Set via: murmur set environment my-env
name: my-env
substrate: gce
machine_type_ref: default
disk_size_gb: 50
startup_script: |
  #!/bin/bash
  set -e
  
  # Install additional packages
  apt-get update && apt-get install -y postgresql-client redis-tools
  
  # Install project-specific tools
  npm install -g pnpm@latest
  
  # Write configuration files
  cat > /home/user/.npmrc << 'EOF'
  registry=https://npm.example.com/
  EOF
  
  # Clone additional repos or download data
  curl -sL https://example.com/fixtures.tar.gz | tar xz -C /tmp/

What startup scripts are good for

Installing packages with apt-get
Installing language-specific tools (pip install, npm install -g, go install)
Writing configuration files (.npmrc, .env, tool configs)
Downloading test fixtures or seed data
Running database migrations or setup scripts
Setting up SSH keys for private package registries

Execution details

Scripts run as root before the agent session starts
The working directory is /
The agent’s repos have already been cloned when the script runs
Scripts must exit 0; a non-zero exit fails the provisioning
stdout and stderr are captured in provisioning logs

Custom images

For larger or more complex environments, bake a custom image instead of relying on startup scripts. 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, reference the resulting image in your workspace configuration. The image is stored in your tenant’s image registry and used for all VMs in the workspace.

When the image is used

Custom images replace the base image entirely. When a VM boots with a custom image, it already has all your tools installed — no startup script delay.

Environment variables on VMs

Agent VMs have several environment variables available:

Variable	Description
`ANTHROPIC_MODEL`	The model configured for this agent (e.g. `claude-sonnet-4-20250514`)
`GH_TOKEN`	GitHub token for repo operations (PR creation, cloning, API calls)
`MURMUR_SECRET_*`	Tenant secrets injected as environment variables. A secret named `npm-token` becomes `MURMUR_SECRET_NPM_TOKEN`.
`MURMUR_AGENT_ID`	The unique identifier for this agent session
`HOME`	Home directory for the agent user

Tenant secrets

Secrets stored in the catalog are decrypted and injected as environment variables with the MURMUR_SECRET_ prefix:

# If you have a catalog secret named "npm-token":
echo $MURMUR_SECRET_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

The Claude Code settings.json is written at VM boot time by the Murmur control plane. It configures:

Model selection — set from the workspace config or per-agent override
Fast mode — enabled if fast_mode: true in the workspace config
MCP server — the murmur MCP server entry, enabling agent orchestration tools
Permissions — tool permissions appropriate for autonomous operation

{
  "model": "claude-sonnet-4-20250514",
  "mcpServers": {
    "murmur": {
      "command": "murmur",
      "args": ["mcp"],
      "env": {}
    }
  },
  "permissions": {
    "allow": [
      "Bash(*)",
      "Read(*)",
      "Write(*)",
      "Edit(*)",
      "Glob(*)",
      "Grep(*)",
      "mcp__murmur__*"
    ]
  }
}

Agents should not modify settings.json directly. To customize Claude Code behavior, use append_system_prompt in the spawn configuration or define an agent persona.

Scripts vs. baked images

Use this decision table to choose between startup scripts and custom images:

Criteria	Startup script	Custom image
Install time	Runs on every boot (adds to startup latency)	Pre-installed (no boot delay)
Install size	Small packages, quick installs	Large toolchains (Go, Rust, Docker, CUDA)
Iteration speed	Change the script, next spawn uses it	Requires a bake (minutes to build)
Complexity	Simple apt-get, npm, pip installs	Complex multi-step installations
Reproducibility	Depends on external package registries at boot time	Fully baked, no external dependencies at boot
Use case	Development, rapid iteration, light customization	Production, stable environments, heavy toolchains

Rules of thumb

If the install takes under 30 seconds, use a startup script.
If the install takes over 2 minutes, bake it into an image.
If you are iterating frequently on the environment, start with a startup script and bake once it stabilizes.
If you need GPU drivers or CUDA, always use a custom image — these installations are too large and slow for startup scripts.
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 startup script for lightweight, frequently-changing configuration (writing config files, setting env vars).

Getting Started

Core Concepts

Guides

Agent VM environment and runtime

Pre-installed tools

The base image provisioning script

Startup scripts

What startup scripts are good for

Execution details

Custom images

Recipes

Baking an image

When the image is used

Environment variables on VMs

Tenant secrets

Claude Code configuration

Scripts vs. baked images

Rules of thumb

​Pre-installed tools

​The base image provisioning script

​Startup scripts

​What startup scripts are good for

​Execution details

​Custom images

​Recipes

​Baking an image

​When the image is used

​Environment variables on VMs

​Tenant secrets

​Claude Code configuration

​Scripts vs. baked images

​Rules of thumb

Pre-installed tools

The base image provisioning script

Startup scripts

What startup scripts are good for

Execution details

Custom images

Recipes

Baking an image

When the image is used

Environment variables on VMs

Tenant secrets

Claude Code configuration

Scripts vs. baked images

Rules of thumb