murmur setup CLI command

Gathers your credentials, discovers your tenant and workspace, encrypts your profile, and writes the local config file (murmur.local.yaml). Run this once per repo to get ready to spawn agents.

Synopsis

murmur setup [flags]
murmur setup --mcp
murmur setup subscription <add|update|remove|list> [flags]
murmur setup connection <add|list|remove|presets> [flags]

murmur setup takes no positional arguments. The subscription and connection subcommands must come directly after setup.

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 to the server for dashboard spawning. In interactive mode, you are prompted. Default: `false`.
`--identity`	string	no	Named keychain identity this repo uses. Saved to `murmur.local.yaml` as `identity_name`. Default: the repo’s current selection, or `default`.
`--mcp`	bool	no	Run only the MCP registration step (register murmur with the agent CLIs on `PATH`) and exit. Takes no other flags. Default: `false`.

What it does

Interactive murmur setup runs eight sections:

Control plane: Reports the murmur API server address setup talks to.
Sign in: Chooses how murmur verifies who you are: your gh CLI login (recommended), or a one-time device-flow code from murmur’s GitHub App. If the gh token cannot serve as identity (for example, it is a personal access token), setup falls back to the device flow. A device-flow identity is stored in the OS keychain.
GitHub access: Chooses the token agents act with on GitHub: from the gh CLI (refreshed with gh auth token on every spawn), or a fixed token you paste (for example, a bot account’s PAT). If gh is not authenticated, setup runs gh auth login for you.
Tenant & workspace: Lists the tenants you belong to and lets you pick one. A single tenant is selected automatically. Then lists workspaces for that tenant. If .murmur/murmur.yaml does not exist, setup asks before creating it.
Claude: Uses ANTHROPIC_API_KEY from the environment, signs in with a Claude subscription (OAuth), takes a pasted Anthropic API key, or skips. Without a Claude credential, Claude agents run on murmur-billed inference.
OpenAI / Codex: Uses OPENAI_API_KEY from the environment, signs in with a ChatGPT subscription (OAuth), takes a pasted OpenAI API key, or skips. Without one, Codex agents run on murmur-billed inference.
Git & SSH: Offers to generate an ed25519 SSH key when ~/.ssh has none, and offers to set up commit signing.
Save & finish: Creates or updates .murmur/murmur.yaml (shared team config) with your tenant and workspace. A newly created file also adds .murmur/murmur.local.yaml to .gitignore. Encrypts your credentials and writes murmur.local.yaml (personal, gitignored). Optionally uploads your profile so you can spawn agents from the dashboard. A subscription credential gathered in this run is always uploaded. Finally, offers to register murmur as an MCP server with Claude Code (claude mcp add -s user murmur -- <murmur> mcp) and Codex (codex mcp add murmur -- <murmur> mcp).

On a re-run, sections whose recorded credential is still usable offer to keep it.

MCP registration only

murmur setup --mcp runs step 8’s MCP registration by itself. Each prompt defaults to yes. It fails when neither claude nor codex is on PATH, or when a registration you confirmed does not complete.

Non-interactive mode

With --non-interactive, murmur 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 subscription OAuth access token. Requires `--upload`.
`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.
`MURMUR_GH_PAT`	GitHub personal access token agents act with. Validated, then stored in the encrypted profile.
`MURMUR_IDENTITY_TOKEN`, `MURMUR_AUTH_METHOD`	Identity token and its method (for example, `github_oauth`). Set both or neither.

All backend credentials are optional. Without one, agents on that backend run on murmur-billed inference. Without --upload, the profile is written locally and not uploaded.

Subscriptions and connections

murmur setup subscription manages the Claude (Anthropic) and Codex (OpenAI/ChatGPT) subscriptions that spawns round-robin across. murmur setup connection manages the inference connections that opencode models run on. See murmur setup subscription and murmur setup connection.

Examples

Interactive setup in a new repo

murmur setup

Abbreviated output (prompts omitted):

murmur setup — 8 sections, about a minute:
  1. Control plane       which murmur server to talk to
  2. Sign in             how murmur verifies who you are
  3. GitHub access       the GitHub account agents act as
  4. Tenant & workspace  where your agents live
  5. Claude              credential for the Claude backend
  6. OpenAI / Codex      credential for the Codex backend
  7. Git & SSH           commit signing and VM access
  8. Save & finish       write config, upload profile, extras

── [1/8] Control plane ─────────────────────────────────────
   Which murmur server to talk to.
  ! No .murmur/murmur.yaml found — setup will create it.
    API server address: api.murmur.dev:9090

── [2/8] Sign in ───────────────────────────────────────────
  • Discovering GitHub token via gh CLI...
  ✓ gh CLI authenticated as "alice"
  ✓ Signed in as "alice" (gh CLI login).
...
── [4/8] Tenant & workspace ────────────────────────────────
  • Discovering tenants via api.murmur.dev:9090...
    Using personal tenant: github_oauth/alice
  • Discovering workspaces via api.murmur.dev:9090...
    Using workspace: backend
...
── [8/8] Save & finish ─────────────────────────────────────
  • Resolving identity...
    identity: github_oauth/alice
  • Gathering credentials and SSH keys...
    Alice Smith <alice@example.com> (github: alice)
    2 SSH key(s)
  • Uploading credentials to CatalogUser...
  ✓ Credentials uploaded to CatalogUser
  ✓ Wrote .murmur/murmur.local.yaml (identity: github_oauth/alice)

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

Non-interactive setup in CI

export ANTHROPIC_API_KEY="sk-ant-..."
murmur setup --non-interactive --skip-ssh-keys --upload

Write local config to stdout

murmur setup --out -

Register the MCP server only

murmur setup --mcp

Errors

Code	Meaning	What to do
`gh CLI not found — install it from https://cli.github.com`	The `gh` CLI is not installed.	Install it from cli.github.com, or choose the device-flow sign-in and a fixed GitHub token.
`non-interactive setup requires an existing config`	Non-interactive mode requires an existing `.murmur/murmur.yaml`.	Run interactive `murmur setup` first, or create `.murmur/murmur.yaml` manually.
`no tenants found`	Your account is not associated with any tenant.	Contact your organization admin to be added.
`murmur.yaml is required — create .murmur/murmur.yaml manually and re-run setup`	You declined creating `.murmur/murmur.yaml`.	Re-run `murmur setup` and accept, or create the file manually.
`CLAUDE_CODE_OAUTH_TOKEN is a subscription credential ... re-run with --upload`	Non-interactive mode captured a subscription token without `--upload`.	Add `--upload`.
`MURMUR_IDENTITY_TOKEN and MURMUR_AUTH_METHOD must be set together`	Only one of the two variables is set.	Set both or neither.
`--mcp runs the MCP registration step alone and takes no other flags`	`--mcp` was combined with another flag.	Run `murmur setup --mcp` by itself.
`configure MCP servers: no agent CLI on PATH`	`--mcp` found neither `claude` nor `codex`.	Install Claude Code or Codex, then re-run.
`murmur setup takes no arguments`	A positional argument was passed.	Put subcommands first, as in `murmur setup subscription add`.

Profiles and secrets: what the profile contains and how credentials are stored
Workspaces: concept overview
murmur login: sign in without running full setup
murmur setup subscription: manage Claude and Codex subscriptions
murmur setup connection: manage inference connections
murmur auth: standalone Claude OAuth flow
murmur init: onboarding wizard for new repos
murmur spawn: start an agent
Configuration: murmur.yaml: shared team config file
Configuration: local overlays: per-developer local config

Getting Started

Core Concepts

Guides

murmur setup CLI command

Synopsis

Arguments

What it does

MCP registration only

Non-interactive mode

Subscriptions and connections

Examples

Interactive setup in a new repo

Non-interactive setup in CI

Write local config to stdout

Register the MCP server only

Errors

​Synopsis

​Arguments

​What it does

​MCP registration only

​Non-interactive mode

​Subscriptions and connections

​Examples

​Interactive setup in a new repo

​Non-interactive setup in CI

​Write local config to stdout

​Register the MCP server only

​Errors

​Related

Synopsis

Arguments

What it does

MCP registration only

Non-interactive mode

Subscriptions and connections

Examples

Interactive setup in a new repo

Non-interactive setup in CI

Write local config to stdout

Register the MCP server only

Errors

Related