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

> Configure your developer profile — GitHub credentials, SSH keys, default tenant, default workspace, and Murmur API host for the CLI.

Gathers your credentials, discovers your [tenant](/concepts/overview) and [workspace](/concepts/workspaces), encrypts your [profile](/concepts/secrets), and writes the local config file (`murmur.local.yaml`). Run this once per repo to get ready to [spawn](/cli/spawn) agents.

## Synopsis

```bash theme={null}
murmur setup [flags]
murmur setup auth <add|update|list> [<label>] [--service-profile NAME]
```

## Arguments

| Name                | Type   | Required | Description                                                                                                                                       |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--out`             | string | no       | Write local config to this path. Use `-` for stdout. Default: `murmur.local.yaml` in the `.murmur/` directory.                                    |
| `--non-interactive` | bool   | no       | Skip prompts and the OAuth flow — read credentials from environment variables instead. Requires an existing `murmur.yaml`. Default: `false`.      |
| `--skip-ssh-keys`   | bool   | no       | Skip SSH key discovery. Use in environments without key pairs. Default: `false`.                                                                  |
| `--commit-signing`  | bool   | no       | Upload a signing key to GitHub for verified commits. In interactive mode, you are prompted when this flag is not set. Default: `false`.           |
| `--upload`          | bool   | no       | Upload your developer [profile](/concepts/secrets) to the server for dashboard spawning. In interactive mode, you are prompted. Default: `false`. |

## What it does

In interactive mode, [`murmur setup`](/cli/setup) walks through these steps:

1. **GitHub authentication** — Discovers your GitHub token via the `gh` CLI. If `gh` is not authenticated, opens `gh auth login` for you.
2. **Tenant selection** — Lists the [tenants](/concepts/overview) you belong to and lets you pick one. If only one tenant exists, it is selected automatically.
3. **Workspace selection** — Lists [workspaces](/concepts/workspaces) for the selected tenant and lets you pick one.
4. **Claude credentials** — Prompts for an Anthropic API key, or offers to run a Claude OAuth flow for subscription-based access. Skippable if you use an OpenAI key instead.
5. **OpenAI credentials** — Checks for `OPENAI_API_KEY` in the environment and prompts for confirmation.
6. **`murmur.yaml` creation** — Creates `.murmur/murmur.yaml` (shared team config) if it does not exist, with your tenant and workspace. Adds `murmur.local.yaml` to `.gitignore`.
7. **Profile encryption** — Encrypts your credentials and writes `murmur.local.yaml` (personal, gitignored).
8. **Profile upload** — Optionally uploads your [profile](/concepts/secrets) so you can [spawn](/cli/spawn) agents from the [dashboard](/guides/dashboard).
9. **MCP server** — If Claude Code is installed, offers to register murmur as an MCP server (`claude mcp add`).

### Non-interactive mode

With `--non-interactive`, [`murmur setup`](/cli/setup) reads credentials from environment variables instead of prompting. An existing `.murmur/murmur.yaml` is required. The recognized variables are:

| Variable                          | Purpose                                          |
| --------------------------------- | ------------------------------------------------ |
| `CLAUDE_CODE_OAUTH_TOKEN`         | Claude OAuth access token.                       |
| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude OAuth refresh token.                      |
| `ANTHROPIC_API_KEY`               | Anthropic API key (alternative to OAuth tokens). |
| `OPENAI_API_KEY`                  | OpenAI API key for Codex backend.                |

At least one of a Claude OAuth token, an Anthropic API key, or an OpenAI API key is required.

## murmur setup auth

`murmur setup auth` manages the labeled Claude OAuth credential set that [spawns](/cli/spawn) round-robin across. The legacy single credential from `murmur setup` is entry 0, label `default`.

| Subcommand       | Description                                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `add <label>`    | Run the OAuth flow and add a labeled credential to the rotation.                                                 |
| `update <label>` | Run the OAuth flow and rotate a labeled credential's values in place (`update default` rotates the legacy pair). |
| `list`           | Show the credential set — labels and secret names, never values.                                                 |

Your credentials are recorded in `murmur.local.yaml` — the source of truth, with every token value KMS-encrypted like the rest of the file — and after each change you are asked whether to upload them to your developer [profile](/concepts/secrets). The upload mirrors the file: it overwrites the profile's Claude credential state from `murmur.local.yaml`. Declining leaves the profile stale; `murmur setup auth update <label>` re-runs the flow and offers the upload again. To remove a credential, delete its entry from `murmur.local.yaml` and re-run `murmur setup` with upload.

Selection is server-side and does not require an upload: [spawns](/cli/spawn) from this machine (CLI or MCP) carry the full local rotation on the request, and the server assigns each spawn one credential from it (round-robin). The uploaded profile is what dashboard spawns select from — keep it mirrored if you spawn from the [dashboard](/guides/dashboard).

With `--service-profile NAME`, the subcommands manage a service profile's credential set instead. Service-profile credentials are server-only and never touch `murmur.local.yaml`; removal is a profile resource edit.

```bash theme={null}
murmur setup auth add user2          # Add a second Claude subscription to the rotation
murmur setup auth update user2       # Re-authenticate after a claude credential "user2" error
murmur setup auth update default     # Rotate the legacy credential
murmur setup auth list --service-profile ci-builder
```

## Examples

### Interactive setup in a new repo

```bash theme={null}
murmur setup
```

```
▸ Discovering GitHub token...
✓ gh CLI authenticated as "alice"
  Use this token? [Y/n] y
▸ Discovering tenants...
  Using personal tenant: github_oauth/alice
▸ Discovering workspaces...
  Using workspace: backend
▸ Authenticating with Claude...
✓ Authenticated (expires in 31536000 seconds, scopes: user:profile user:inference user:file_upload)
▸ Resolving identity...
  identity: github_oauth/alice
▸ Gathering credentials and SSH keys...
  Alice Smith <alice@example.com> (github: alice)
  2 SSH key(s)
✓ Wrote .murmur/murmur.local.yaml (identity: github_oauth/alice)
  Upload developer profile to the server for dashboard spawning? [Y/n] y
▸ Uploading credentials to CatalogUser...
✓ Credentials uploaded to CatalogUser

✓ Setup complete — you're ready to use murmur.
```

### Non-interactive setup in CI

```bash theme={null}
export ANTHROPIC_API_KEY="sk-ant-..."
murmur setup --non-interactive --skip-ssh-keys --upload
```

### Write local config to stdout

```bash theme={null}
murmur setup --out -
```

## Errors

| Code                                                                                           | Meaning                                                | What to do                                                                                        |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `gh CLI not found`                                                                             | The `gh` CLI is not installed.                         | Install it from [cli.github.com](https://cli.github.com).                                         |
| `no .murmur/murmur.yaml found`                                                                 | Non-interactive mode requires an existing config file. | Run interactive [`murmur setup`](/cli/setup) first, or create `.murmur/murmur.yaml` manually.     |
| `no tenants found`                                                                             | Your GitHub account is not associated with any tenant. | Contact your organization admin to be added.                                                      |
| `at least one of a Claude OAuth token, an Anthropic API key, or an OpenAI API key is required` | No credentials were provided.                          | Supply at least one credential via the interactive prompts or environment variables.              |
| `murmur.yaml is required`                                                                      | No config file exists and creation was declined.       | Run [`murmur setup`](/cli/setup) from a git repository, or create `.murmur/murmur.yaml` manually. |

## Related

* [Profiles and secrets](/concepts/secrets) — what the profile contains and how credentials are stored
* [Workspaces](/concepts/workspaces) — concept overview
* [`murmur auth`](/cli/auth) — standalone Claude OAuth flow
* [`murmur init`](/cli/init) — onboarding wizard for new repos
* [`murmur spawn`](/cli/spawn) — start an agent
* [Configuration: murmur.yaml](/configuration/murmur-yaml) — shared team config file
* [Configuration: local overlays](/configuration/local-overlays) — per-developer local config