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

> Add, list, or remove the inference connections (endpoint plus API key) that opencode model strings run on, and list the provider presets.

Manages your inference connections. A connection is what an opencode model string names before its first slash: `murmur spawn --model openrouter/qwen/qwen3-coder` runs on the connection with id `openrouter`. The id selects the endpoint and the key, and nothing else.

Agents reach the endpoint through Murmur's inference gateway, which attaches the stored key. The key never lands on a VM. It is stored as the secret `CONNECTION_<ID>_API_KEY` (id upper-cased, hyphens turned into underscores), which must not already exist. A service profile's secret also carries the profile name, `CONNECTION_<PROFILE>_<ID>_API_KEY`, because its secrets are tenant-wide.

## Synopsis

```bash theme={null}
murmur setup connection add [flags] [--service-profile NAME]
murmur setup connection list [--service-profile NAME]
murmur setup connection remove --id ID [--service-profile NAME]
murmur setup connection presets
```

`ls` is an alias for `list`, and `rm` for `remove`. The subcommands take flags only.

## Subcommands

| Subcommand | Description |
| - | - |
| `add` | Store an API key and add a connection to your profile. |
| `list` | Show the configured connections: ids, endpoints, and secret names, never keys. |
| `remove` | Remove a connection and delete its key secret. |
| `presets` | Show the models.dev providers that `add --provider` can be seeded from. |

## Provider and protocol

`--provider` associates a connection with a [models.dev](https://models.dev) provider. The provider's catalog fills the dashboard's model list and prices the agent's turns. It never decides where a call is sent or which key it carries. Two connections can share one provider, for example `fireworks-dev` and `fireworks-prod` with separate keys, both `--provider fireworks-ai`. A connection to an endpoint the catalog does not list needs no provider: its models are typed by hand and its turns are reported unpriced.

Every connection records the wire protocol its endpoint speaks. The gateway forwards that protocol, and it selects the SDK driver the agent loads:

| Protocol | Request |
| - | - |
| `openai-chat-completions` | `POST {base-url}/chat/completions` |
| `openai-responses` | `POST {base-url}/responses` |
| `anthropic-messages` | `POST {base-url}/messages` |
| `google-generative-ai` | `POST {base-url}/models/{model}:generateContent` |
| `xai-responses` | `POST {base-url}/responses`, in api.x.ai's own shape |

The two Responses protocols post to the same path and differ in the body. Use `xai-responses` for an xAI endpoint and `openai-responses` for api.openai.com and endpoints that mirror it.

When `--provider` names a preset, the preset's protocol, endpoint, and name fill in any flags you omit. Otherwise `--protocol` and `--base-url` are required. Presets are catalog metadata, not proof of access: the key decides what the connection serves.

## `add` flags

| Name | Type | Default | Description |
| - | - | - | - |
| `--id` | string | `--provider` | Connection id: the model string's first segment. A lowercase DNS label, `[a-z][a-z0-9-]{0,62}`. Required when the provider id is not a valid connection id, for example `--provider wafer.ai --id wafer-prod`. |
| `--provider` | string | none | models.dev provider id whose catalog lists and prices the connection's models, for example `openrouter` or `fireworks-ai`. |
| `--protocol` | string | from preset | One of the protocols above. Required unless the preset supplies it. |
| `--base-url` | string | from preset | The https origin the gateway calls, for example `https://openrouter.ai/api/v1`. Required unless the preset publishes one. |
| `--name` | string | preset's name, else `--id` | Label shown in the dashboard. |
| `--model` | string | none | Model id the connection offers in the dashboard's picker: the model string's second segment. Repeatable. Listed next to the provider's catalog, so a connection with no provider still offers a pick list. This advertises models; it does not restrict them. `murmur spawn --model` accepts any `<connection>/<model>`. |
| `--api-key-stdin` | bool | `false` | Read the key from stdin instead of prompting. |

## Common flags

| Name | Type | Required | Description |
| - | - | - | - |
| `--service-profile` | string | no | Manage a [service profile's](/concepts/service-profiles) connections instead of your own. Not accepted by `presets`. |
| `--id` | string | `remove` | The connection to remove. |

## Output

`add` and `remove` print a success line on stderr:

```
✓ Stored github_oauth/alice/CONNECTION_OPENROUTER_API_KEY and added connection "openrouter" (openai-chat-completions, https://openrouter.ai/api/v1; provider openrouter) to your developer profile
✓ Removed connection "acme-llm" from your developer profile and deleted secret github_oauth/alice/CONNECTION_ACME_LLM_API_KEY
```

`list` prints a table:

```
ID          NAME        PROVIDER    PROTOCOL                 BASE URL                      MODELS                         KEY SECRET
openrouter  OpenRouter  openrouter  openai-chat-completions  https://openrouter.ai/api/v1                                 github_oauth/alice/CONNECTION_OPENROUTER_API_KEY
acme-llm    acme-llm                openai-chat-completions  https://llm.acme.example/v1   qwen3-coder-480b,gpt-oss-120b  github_oauth/alice/CONNECTION_ACME_LLM_API_KEY
```

With no connections, `list` prints a hint to stderr instead.

`presets` prints a table of providers:

```
PROVIDER      NAME          PROTOCOL                 BASE URL                                DOCS
openrouter    OpenRouter    openai-chat-completions  https://openrouter.ai/api/v1            https://openrouter.ai/models
fireworks-ai  Fireworks AI  openai-chat-completions  https://api.fireworks.ai/inference/v1/  https://fireworks.ai/docs/
```

When the models.dev catalog is unavailable, `presets` says so on stderr. A connection can still be added with `--protocol` and `--base-url`.

## Examples

### Add a connection from a preset

```bash theme={null}
murmur setup connection add --provider openrouter
```

The command prompts for the API key.

### Two connections for one provider

```bash theme={null}
murmur setup connection add --id fireworks-dev --provider fireworks-ai
murmur setup connection add --id fireworks-prod --provider fireworks-ai --service-profile deploy
```

### A self-hosted endpoint

```bash theme={null}
murmur setup connection add --id acme-llm --protocol openai-chat-completions \
  --base-url https://llm.acme.example/v1 \
  --model qwen3-coder-480b --model gpt-oss-120b \
  --api-key-stdin < key.txt
```

Spawn on it with `murmur spawn --model acme-llm/qwen3-coder-480b`.

### A preset with an explicit endpoint

```bash theme={null}
murmur setup connection add --id gemini --provider google --base-url https://generativelanguage.googleapis.com/v1beta
```

### List and remove

```bash theme={null}
murmur setup connection list --service-profile deploy
murmur setup connection remove --id acme-llm
```

## Errors

| Code | Meaning | What to do |
| - | - | - |
| none | `--id or --provider is required — see 'murmur setup connection help'` | Pass `--id`, `--provider`, or both. |
| none | `connection id "<id>" must be a lowercase DNS label ([a-z][a-z0-9-]{0,62}) ...` | Pass an `--id` of your own when the provider id is not a DNS label. |
| none | `connection "<id>" already exists in <profile> — remove it first with 'murmur setup connection remove --id <id>'` | Remove the existing connection, or choose another id. |
| none | `missing --protocol and --base-url: ...` | No `--provider` names a preset, so `--protocol` and `--base-url` are both required. The message names only the ones you left out (`missing --base-url: ...` when just that one is missing). Pass the flags it lists. |
| none | `--model "<model>" must be 1-256 printable ASCII characters with no spaces or commas ...` | Fix the model id. |
| none | `--model "<model>" is given twice` | Pass each model once. |
| none | `no API key given for connection "<id>"` | Enter a key at the prompt, or pipe one with `--api-key-stdin`. |
| none | `secret <name> already exists in <profile> — ...` | Remove the connection that holds the secret, or delete the secret with the command the message names. |
| none | `--id is required — see 'murmur setup connection help'` | `remove` needs `--id`. |
| none | `connection "<id>" is not configured in <profile> — see 'murmur setup connection list'` | Check ids with `murmur setup connection list`. |
| none | `unexpected argument(s) "<args>" in 'murmur setup connection <cmd>'` | The subcommands take flags only. |

## Related

* [`murmur setup`](/cli/setup): bootstrap a repo and your developer profile
* [`murmur setup subscription`](/cli/setup-subscription): manage Claude and Codex subscriptions
* [`murmur spawn`](/cli/spawn): run an agent with `--model <connection>/<model>`
* [Model selection](/configuration/model-selection): choosing models
* [Agent runtimes](/guides/agent-runtimes): the runtimes agents can use