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

# mutagent providers

> Add, copy, test, and manage the LLM providers whose API keys your cloud sessions use.

An LLM provider holds the API key for your models. LLM providers belong to one workspace, and every
Helix Cloud session in that workspace uses them to call your models. Keys are stored encrypted and
are never shown again.

## Before you start

* Sign in and select a workspace: see [Installation](/cli/installation). Every command on this page
  works in the selected workspace, or the one `--workspace <name-or-id>` names.
* Have the LLM provider's API key in a file or an environment variable, so you can pipe it in with
  `--api-key-stdin`. The global `--api-key` flag is your Mutagent key, not this one.
* A coding agent runs `mutagent providers list --json` first to see whether the LLM provider already
  exists, and confirms with you before any command that writes or deletes a key.

## mutagent providers mirror

Copy the API keys from your local Helix setup into the workspace as LLM providers. The command shows
what it will copy and asks first. If the workspace has no default model, it sets one. Mirroring does
not test the keys: check `mutagent helix models` afterwards, then run a model.

```bash theme={null}
mutagent providers mirror
```

| Flag | What it does |
| - | - |
| `-y, --yes` | Copy without asking. Required when there is no terminal. |
| `--no-overwrite` | Leave LLM providers the workspace already has unchanged. |
| `--provider <id>` | Copy only this local LLM provider. Repeat the flag for more than one. |
| `--workspace <name-or-id>` | Copy into this workspace instead of the selected one. This is the flag every command takes. |
| `--channel <stable\|rc>` | Read the `stable` or `rc` Helix setup. The default is `stable`. |

| Exit code | Meaning |
| - | - |
| 0 | The copy finished. |
| 1 | Not confirmed, so nothing was written (with `--json`, the output contains the plan), or at least one entry failed (the report names it). |
| 3 | You are not signed in, or no workspace is set. |

From a coding agent, run it in two steps. First, without `--yes`: it sends nothing, exits 1, and
the JSON output holds the plan. Show the plan to the person, including endpoint and API format
changes. Only after they agree, run it again with `--yes`:

```bash theme={null}
mutagent providers mirror --json          # the plan; nothing is sent
mutagent providers mirror --yes --json    # after the person agrees
```

When the run sets the workspace default model, `workspaceDefaultModelSet` names it.

See [LLM providers and models](/helix/cloud/setup#mirror-your-local-helix-setup) for what is and is
not copied.

## mutagent providers add

Add an LLM provider. The key is tested against the LLM provider before it is saved. If the test
fails, nothing is saved and the LLM provider's error is shown. If the workspace has no default model
yet, adding a provider with a key sets one. An existing default is never changed.

Pass the key on stdin with `--api-key-stdin`, so it stays out of your shell history:

```bash theme={null}
mutagent providers add --provider openai --name "OpenAI" --api-key-stdin < openai-key.txt
printf %s "$OPENAI_API_KEY" | mutagent providers add --provider openai --name "OpenAI" --api-key-stdin
```

| Flag | What it does |
| - | - |
| `-p, --provider <type>` | Required. One of `openai`, `anthropic`, `google`, `moonshot`, `glm`, `zai-coding-plan`, `deepseek`, `xai`, `openrouter`, `azure`, `vertex`, `bedrock`, `custom`. |
| `-n, --name <name>` | Required. A display name. |
| `--api-key-stdin` | Read the API key from stdin. One trailing newline is dropped. Required for every type except `vertex`, unless you pass `--api-key`. |
| `-k, --api-key <key>` | The API key on the command line, where shell history keeps it. Give this or `--api-key-stdin`, not both. |
| `--base-url <url>` | Send requests to this URL instead of the LLM provider's default. |
| `--set-default` | Make this the default LLM provider of its type. |

`azure`, `vertex`, `bedrock`, and `custom` take extra flags:

| Type | Extra flags |
| - | - |
| `azure` | `--hosted-family <openai\|anthropic>`, `--resource-endpoint <url>`, `--deployment-name <name>`, `--api-version <version>` |
| `vertex` | `--hosted-family <gemini\|anthropic>`, `--service-account-key <json>` instead of `--api-key`, `--project-id <id>`, `--region <region>` |
| `bedrock` | `--region <region>`. Bedrock serves Anthropic models, so it takes no `--hosted-family`. |
| `custom` | `--base-url <url>`; `--api-format <openai\|anthropic>`: `anthropic` when the endpoint speaks the Anthropic API. The base URL must be a public address. |

`zai-coding-plan` is the Z.AI GLM Coding Plan. It takes only an API key: its address is fixed, so
`--base-url` is refused.

```bash theme={null}
mutagent providers add --provider bedrock --name "Bedrock Claude" --api-key-stdin --region us-east-1 < bedrock-key.txt
```

With `--json`, success returns `"success": true` with the new LLM provider's `id`, `name` and
`workspaceId`, and the command exits 0. Then check it:

```bash theme={null}
mutagent providers test <provider-id> --json
```

## mutagent providers list

List the workspace's LLM providers.

```bash theme={null}
mutagent providers list --json
```

The JSON has a `data` array. Each entry has `id`, `name`, `provider` (the type), `baseUrl`,
`isActive` and `isDefault`. Use the `id` with `get`, `test`, `update` and `delete`.

| Flag | What it does |
| - | - |
| `-m, --models` | Also show the catalogue models for each LLM provider type. For the models cloud runs can use, run `mutagent helix models`. |
| `-t, --type <type>` | Only list LLM providers of this type. |
| `-l, --limit <n>` | Return at most `n`. The default is 50. |
| `-o, --offset <n>` | Skip the first `n`. |

## mutagent providers get

Show one LLM provider. The key is masked.

```bash theme={null}
mutagent providers get <provider-id>
```

## mutagent providers test

Test the saved key against the LLM provider again, and list the models the LLM provider reports.

```bash theme={null}
mutagent providers test <provider-id> --json
```

A passing test exits 0. A failing test exits 1 with the error code `PROVIDER_TEST_FAILED` and the LLM
provider's own error.

## mutagent providers update

Change an LLM provider. Only the flags you pass change. An update never changes the workspace default
model.

```bash theme={null}
mutagent providers update <provider-id> --active false
```

| Flag | What it does |
| - | - |
| `-n, --name <name>` | New display name. |
| `--api-key-stdin` | Read the new API key from stdin. |
| `-k, --api-key <key>` | New API key on the command line. Give this or `--api-key-stdin`, not both. |
| `--base-url <url>` | New base URL. `""` removes it. |
| `--active <true\|false>` | Turn the LLM provider on or off. |
| `--set-default` | Make this the default LLM provider of its type. |

## mutagent providers delete

Remove an LLM provider.

```bash theme={null}
mutagent providers delete <provider-id> --force
```

| Flag | What it does |
| - | - |
| `-f, --force` | Required. The command never asks for confirmation: without `--force` it refuses and deletes nothing. The stored key cannot be recovered. |

`mutagent providers rm` is the same command. `mutagent providers ls` is the same as `list`.

## OpenRouter

OpenRouter is one of the LLM provider types. One OpenRouter key gives your cloud runs models from many
vendors through your OpenRouter account.

```bash theme={null}
mutagent providers add --provider openrouter --name "OpenRouter" --api-key-stdin < openrouter-key.txt
```

Every model your key can reach on OpenRouter is available to your cloud runs. `mutagent helix models`
lists them after you add the provider.

## If it fails

| Exit code | Cause | Fix |
| - | - | - |
| 3 | Not signed in, or no workspace selected. | See [Installation](/cli/installation). |
| 2 | Your Mutagent key expired or is invalid. | Sign in again: `mutagent login`. |
| 1 | `--api-key-stdin` with nothing piped in, or with both `--api-key` and `--api-key-stdin`. | Pipe the key in once: `... --api-key-stdin < key.txt`. |
| 1 | The key test failed when adding, or `providers test` failed (`PROVIDER_TEST_FAILED`). | Read the LLM provider's error in `error`; check the key, region or base URL. |
| 1 | `delete` without `--force`, or `mirror` without `--yes` and no terminal. | Confirm with the person, then add the flag. |

See [Errors and exit codes](/cli/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.