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 each parent directory for a .murmur/ directory. You can therefore 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)
    hooks/               # repo hooks (see Repo Hooks)
  src/
  ...

Creating the configuration

murmur setup

murmur setup signs you in, lets you pick a tenant and workspace, and writes the tenant and workspace fields to .murmur/murmur.yaml. It asks before creating the file. For CI, murmur setup --non-interactive skips the OAuth flow and prompts and reads credentials from the environment.

Field reference

tenant

tenant:
  provider: github_app
  org: acme

Type: object (required) The tenant your repo belongs to. provider is the identity provider (github_app or google_oidc) and org is the tenant’s org. murmur setup writes this block. Together they form your tenant ID, <provider>/<org> (for example github_app/acme). When it is missing, commands that talk to the API fail with an error that starts tenant.provider not set.

workspace

workspace: my-workspace

Type: string (optional) The default workspace name. Must match a workspace resource in your tenant’s catalog. The workspace resolves repos, images, placements, environments, and other infrastructure configuration. A --workspace flag overrides it. murmur spawn from a laptop needs one of the two and otherwise fails with --workspace is required (or set workspace in murmur.yaml).

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) GitHub App slugs whose CI failures do not wake agents. A failed check suite from a listed app (for example github-actions or socket-security) is dropped instead of starting a self-heal turn. Use it for apps whose failures are:

Flaky: intermittent failures unrelated to the agent’s changes
Irrelevant: checks that do not apply to the type of work agents do

Entries must match the check suite’s app slug exactly, not an individual check run name. Spawned children inherit the list.

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.

service_profile

service_profile: infra-bot

Type: string (optional) The default service profile for spawns that do not pass --service-profile. murmur spawn --propose requires one from either source.

suggest_terminate_mode

suggest_terminate_mode: immediate

Type: string (optional) What murmur suggest-terminate does for agents you spawn: suggest (an advisory delete button) or immediate (terminate the agent). Empty inherits the workspace’s suggest_terminate_mode. murmur spawn --suggest-terminate-mode overrides it per spawn.

sleep_timeout

sleep_timeout: 336h

Type: Go duration string (optional) How long a spawned agent’s VM may stay asleep before the agent ends and its VM is released, between 1h and 8760h. 0 lifts the limit. Empty inherits the workspace’s default_sleep_timeout.

autopilot_timeout

autopilot_timeout: 72h

Type: Go duration string (optional) How long a spawned agent acts on CI results, PR comments, and merge conflicts on its own after the last human interaction, between 1m and 8760h. 0 lifts the limit. Empty inherits the workspace’s default_autopilot_timeout. murmur spawn --autopilot-timeout overrides it per spawn.

public_url

public_url: https://cloud.murmur.dev

Type: string (optional, default: https://cloud.murmur.dev) The dashboard base URL the CLI uses when it prints agent links.

api

api:
  address: api.murmur.dev:9090

Type: object (optional) API connection settings.

api.address

Type: string (optional) The Murmur API server address. Defaults to api.murmur.dev:9090. 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

tenant:
  provider: github_app
  org: acme
workspace: acme-backend
model: sonnet
fast_mode: false
skip_checks:
  - socket-security
api:
  address: api.murmur.dev:9090

Environment variable overrides

Environment variables take precedence over all configuration file values. Use these for CI environments, temporary overrides, or per-shell customization. Every field has an override variable: uppercase its YAML path, join the segments with _, and prefix MURMUR_. For example, MURMUR_WORKSPACE overrides workspace and MURMUR_API_ADDRESS overrides api.address. These variables choose which files load:

Variable	Overrides	Example
`MURMUR_CONTEXT`	Config file selection: loads `murmur.<context>.yaml` and `murmur.<context>.local.yaml`	`dev`
`MURMUR_CONFIG`	Shared config file path	`/etc/murmur/config.yaml`
`MURMUR_LOCAL_CONFIG`	Local overlay file path	`~/.config/murmur/local.yaml`
`MURMUR_CONFIG_START_DIR`	Directory walk-up discovery starts from (default: the working directory)	`/src/my-repo`

MURMUR_CONTEXT cannot be combined with MURMUR_CONFIG or MURMUR_LOCAL_CONFIG, and MURMUR_CONFIG cannot be combined with MURMUR_CONFIG_START_DIR. Setting both of a pair is an error.

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. The local overlay is read from the same directory. 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:

username: jdoe
git_name: Jane Doe
git_email: jdoe@example.com
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

Field reference

tenant

workspace

model

fast_mode

skip_checks

suppress_events

service_profile

suggest_terminate_mode

sleep_timeout

autopilot_timeout

public_url

api

api.address

Complete example

Environment variable overrides

MURMUR_CONFIG

MURMUR_LOCAL_CONFIG

Per-developer overlay

Precedence order

​File location

​Creating the configuration

​Field reference

​tenant

​workspace

​model

​fast_mode

​skip_checks

​suppress_events

​service_profile

​suggest_terminate_mode

​sleep_timeout

​autopilot_timeout

​public_url

​api

​api.address

​Complete example

​Environment variable overrides

​MURMUR_CONFIG

​MURMUR_LOCAL_CONFIG

​Per-developer overlay

​Precedence order

File location

Creating the configuration

Field reference

tenant

workspace

model

fast_mode

skip_checks

suppress_events

service_profile

suggest_terminate_mode

sleep_timeout

autopilot_timeout

public_url

api

api.address

Complete example

Environment variable overrides

MURMUR_CONFIG

MURMUR_LOCAL_CONFIG

Per-developer overlay

Precedence order