murmur.yaml configuration file reference

The .murmur/murmur.yaml file is the shared configuration for your Murmur workspace. It lives in the .murmur/ directory at the root of your repository and is committed to version control. Every developer on the team uses the same file.

File location

The configuration file is located at .murmur/murmur.yaml in your repository root. Murmur uses walk-up discovery — when you run a murmur command, it searches the current directory and all parent directories for a .murmur/ directory. This means you can run Murmur commands from any subdirectory in your repository.

my-repo/
  .murmur/
    murmur.yaml          # shared config (committed to git)
    murmur.local.yaml    # per-developer overlay (gitignored)
    flights/             # flight definitions
  src/
  ...

Creating the configuration

Automatic setup

murmur setup

Auto-detects settings from your tenant and creates the configuration with sensible defaults. Useful for CI environments or when you want to get started quickly without interactive prompts.

Field reference

workspace

workspace: my-workspace

Type: string (required) The workspace name. Must match a workspace resource in your tenant’s catalog. The workspace name is used to resolve repos, images, placements, environments, and other infrastructure configuration.

model

model: opus

Type: string (optional) The default model for agents spawned in this workspace. Valid values:

Value	Model	Best for
`opus`	Claude Opus	Complex reasoning, architecture decisions, multi-file refactors
`sonnet`	Claude Sonnet	Balanced capability and cost, most common tasks
`haiku`	Claude Haiku	Simple tasks, high volume, lowest cost

This sets the workspace default. Individual spawn calls can override the model per-agent using the model parameter or flag, and the workspace default itself overrides a persona’s model. When no source sets a model at all, Claude Code on the VM falls back to its own built-in default — see Model Selection for the full precedence chain.

fast_mode

fast_mode: true

Type: boolean (optional, default: false) When enabled, Anthropic agents use fast mode.

skip_checks

skip_checks:
  - lint
  - typecheck
  - visual-regression

Type: array of strings (optional) A list of CI check names to skip when evaluating whether an agent’s PR is ready. Agents wait for CI checks to pass before considering their work complete. Use skip_checks to exclude checks that are:

Flaky — intermittent failures unrelated to the agent’s changes
Irrelevant — checks that do not apply to the type of work agents do
Slow — optional checks that would unnecessarily delay the agent

Check names must match the exact name reported by GitHub’s check runs API.

suppress_events

suppress_events:
  - ci
  - pr_comments

Type: array of strings (optional) The default GitHub event classes that spawned agents ignore — they are never woken by events of these classes on their branches. Valid values:

Value	Suppresses
`ci`	CI check results (including failures — no self-heal wake)
`pr_comments`	PR comments and PR reviews

Empty or absent means agents react to every class (the default). Suppressed events are still recorded on the agent’s timeline as suppressed, and the dashboard’s PR and CI state keeps updating — only the wake is skipped. Set it in murmur.yaml for a team-wide default, or in murmur.local.yaml to apply it just to your own spawns. Override per spawn with murmur spawn --suppress-events (none forces full subscription) or the MCP suppress_events parameter, and toggle it on a running agent from the dashboard’s event checkboxes.

checks_timeout

checks_timeout: 20m

Type: Go duration string (optional, default: 15m) How long agents wait for CI checks to complete before timing out. Accepts Go duration format:

Example	Duration
`5m`	5 minutes
`15m`	15 minutes (default)
`1h`	1 hour
`1h30m`	1 hour 30 minutes

If your CI pipeline consistently takes longer than 15 minutes, increase this value to avoid premature timeouts.

api

api:
  address: api.murmur.example.com:443

Type: object (optional) API connection settings.

api.address

Type: string (optional) The Murmur API server address. Defaults to the platform’s standard API endpoint. Only change this for:

Custom on-premise deployments
Development environments pointing at a different API
Multi-region setups with a region-specific endpoint

Complete example

workspace: acme-backend
model: sonnet
fast_mode: false
skip_checks:
  - visual-regression
  - e2e-smoke
checks_timeout: 20m
api:
  address: api.murmur.example.com:443

Environment variable overrides

Environment variables take precedence over all configuration file values. Use these for CI environments, temporary overrides, or per-shell customization.

Variable	Overrides	Example
`MURMUR_CONTEXT`	Config file selection	`dev`
`MURMUR_CONFIG`	Shared config file path	`/etc/murmur/config.yaml`
`MURMUR_LOCAL_CONFIG`	Local overlay file path	`~/.config/murmur/local.yaml`

MURMUR_CONFIG

Override the shared config file path entirely:

export MURMUR_CONFIG=/path/to/custom/murmur.yaml

Bypasses walk-up discovery and uses the specified file directly. Useful in CI where the working directory may not contain a .murmur/ directory.

MURMUR_LOCAL_CONFIG

Override the local overlay file path:

export MURMUR_LOCAL_CONFIG=/path/to/custom/murmur.local.yaml

Per-developer overlay

Each developer has a personal overlay file at .murmur/murmur.local.yaml. This file is gitignored and contains developer-specific settings:

developer: jdoe
encrypted_profile: <base64-encoded encrypted data>
ssh_public_keys:
  - ssh-ed25519 AAAA... jdoe@laptop

The local overlay is merged on top of the shared config. Values in the local overlay take precedence over the shared config but are overridden by environment variables. See Local Overlays for the full reference.

Precedence order

When the same setting is specified in multiple places, the highest-precedence source wins:

Environment variables       (highest priority)
    ↓
Local overlay               (.murmur/murmur.local.yaml)
    ↓
Shared config               (.murmur/murmur.yaml)
    ↓
Built-in defaults           (lowest priority)

Getting Started

Core Concepts

Guides

murmur.yaml configuration file reference

File location

Creating the configuration

Automatic setup

Field reference

workspace

model

fast_mode

skip_checks

suppress_events

checks_timeout

api

api.address

Complete example

Environment variable overrides

MURMUR_CONFIG

MURMUR_LOCAL_CONFIG

Per-developer overlay

Precedence order

​File location

​Creating the configuration

​Automatic setup

​Field reference

​workspace

​model

​fast_mode

​skip_checks

​suppress_events

​checks_timeout

​api

​api.address

​Complete example

​Environment variable overrides

​MURMUR_CONFIG

​MURMUR_LOCAL_CONFIG

​Per-developer overlay

​Precedence order

File location

Creating the configuration

Automatic setup

Field reference

workspace

model

fast_mode

skip_checks

suppress_events

checks_timeout

api

api.address

Complete example

Environment variable overrides

MURMUR_CONFIG

MURMUR_LOCAL_CONFIG

Per-developer overlay

Precedence order