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

# Local Overlays

> Per-developer overrides for workspace configuration and environment variables — apply local settings without modifying shared catalog resources.

Murmur supports layered configuration: a shared `murmur.yaml` committed to the repo, a gitignored `murmur.local.yaml` for per-developer credentials, and environment variable overrides for CI or special cases.

## murmur.local.yaml

<Tip>
  Keep `murmur.local.yaml` and all `murmur.*.local.yaml` files in `.gitignore`. The `murmur install` command adds these patterns automatically.
</Tip>

The primary local overlay lives at `.murmur/murmur.local.yaml`. This file is **gitignored** and contains per-developer settings that should not be committed to the repository. It is created automatically by `murmur install` or `murmur setup`.

```yaml theme={null}
developer: jdoe
encrypted_profile: |
  eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTI1NkdDTSIsImVway...
ssh_public_keys:
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ... jdoe@laptop
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK... jdoe@desktop
```

### Fields

#### developer

```yaml theme={null}
developer: jdoe
```

**Type:** string

Your GitHub username. Used to associate agents with your identity, scope agent listings, and determine authorization.

#### encrypted\_profile

```yaml theme={null}
encrypted_profile: <base64-encoded data>
```

**Type:** string

Your encrypted developer profile, generated during `murmur install` or `murmur setup`. This blob contains your Anthropic API credentials and other sensitive configuration, encrypted with the tenant's KMS key. It is transported to agent VMs where the control plane re-seals it with per-VM ephemeral keys and decrypts it in memory only.

#### ssh\_public\_keys

```yaml theme={null}
ssh_public_keys:
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ... jdoe@laptop
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK... jdoe@desktop
```

**Type:** array of strings

SSH public keys authorized for connecting to your agent VMs via `murmur ssh` or `murmur attach`. Add a key for each machine you work from. Keys are injected into the VM's authorized\_keys at boot time.

#### claude\_credentials

```yaml theme={null}
claude_credentials:
  - label: user2
    token:
      ciphertext: <base64-encoded data>
      scheme: GCP_KMS
      key_ref: projects/.../cryptoKeys/...
    refresh_token:
      ciphertext: <base64-encoded data>
      scheme: GCP_KMS
      key_ref: projects/.../cryptoKeys/...
```

**Type:** array of objects

Labeled Claude OAuth credentials, written by [`murmur setup auth add`](/cli/setup#murmur-setup-auth) and rotated by `murmur setup auth update`. Together with the default pair, these form the rotation set that spawns round-robin across: spawns from this machine carry the whole set on the request and the server selects one credential per spawn — no upload needed. Each token value is KMS-encrypted server-side — the same encryption as `encrypted_secrets`; nothing in this file is plaintext, and the rotation itself is never delivered to a VM (each agent receives only its assigned credential). The local file is the source of truth: uploading your profile mirrors this set onto your developer [profile](/concepts/secrets) — what dashboard spawns select from — overwriting its Claude credential state. To remove an entry, delete it here and re-run `murmur setup` with upload.

## Explicit path overrides

For maximum control, bypass walk-up discovery entirely with explicit file paths:

### MURMUR\_CONFIG

```bash theme={null}
export MURMUR_CONFIG=/path/to/custom/murmur.yaml
```

Replaces walk-up discovery. Murmur loads the shared config from this exact path instead of searching for `.murmur/murmur.yaml` up the directory tree.

### MURMUR\_LOCAL\_CONFIG

```bash theme={null}
export MURMUR_LOCAL_CONFIG=/path/to/custom/murmur.local.yaml
```

Overrides the local overlay path. Useful when your local settings live outside the repository, for example in `~/.config/murmur/`.

## Environment variable reference

The full set of environment variables that affect Murmur configuration:

| Variable              | Purpose                                                             | Example                       |
| --------------------- | ------------------------------------------------------------------- | ----------------------------- |
| `MURMUR_CONFIG`       | Explicit path to shared config file (bypasses walk-up discovery)    | `/etc/murmur/config.yaml`     |
| `MURMUR_LOCAL_CONFIG` | Explicit path to local overlay file                                 | `~/.config/murmur/local.yaml` |
| `MURMUR_API_ADDRESS`  | Override API server address (equivalent to `api.address` in config) | `api.murmur.example.com:443`  |
| `MURMUR_WORKSPACE`    | Override workspace name                                             | `my-workspace`                |
| `MURMUR_DEVELOPER`    | Override developer username                                         | `jdoe`                        |

## Precedence rules

When the same setting appears in multiple sources, 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)
```

For named contexts, context-specific files replace the defaults entirely — `murmur.dev.yaml` is loaded instead of `murmur.yaml`, not merged with it. Similarly, `murmur.dev.local.yaml` replaces `murmur.local.yaml`.

Environment variables always take highest precedence, regardless of which context is active.