> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# murmur.yaml Configuration

> Complete reference for the .murmur/murmur.yaml file — workspace settings, model selection, API host, and per-repo configuration loaded by the CLI.

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.

```text theme={null}
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

```bash theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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.

### fast\_mode

```yaml theme={null}
fast_mode: true
```

**Type:** boolean (optional, default: `false`)

When enabled, anthropic agents use fast mode.

### skip\_checks

```yaml theme={null}
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.

### checks\_timeout

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```yaml theme={null}
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](/configuration/local-overlays) for the full reference.

## Precedence order

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

```text theme={null}
Environment variables       (highest priority)
    ↓
Local overlay               (.murmur/murmur.local.yaml)
    ↓
Shared config               (.murmur/murmur.yaml)
    ↓
Built-in defaults           (lowest priority)
```