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

# LLM providers and models

> Connect your LLM providers to the workspace so cloud sessions can call your models, and choose the default model a run uses.

<Note>
  **Early access.** Cloud sessions and managed agent runs are not open to every account yet: we are
  letting accounts in gradually while we test. They run in a cloud sandbox operated by Mutagent, so
  there is nothing to host. A sandbox with nothing to do for 15 minutes stops; send the session a
  message and it wakes up, delivers your message and carries on in the same conversation.
</Note>

Your cloud sessions call your models with your own API keys. Add your LLM providers to the workspace
once, and every session in that workspace can use them. The keys are stored encrypted.

## Before you start

* The `mutagent` CLI is installed. See [Installation](/cli/installation).
* You are signed in. In a terminal, run `mutagent login`. Without a browser, set `MUTAGENT_API_KEY`
  and run `mutagent login --json`. A coding agent helping a person runs
  `mutagent login --browser --json` and shows them the printed URL. See [Sign in](/cli/commands/login).
* A workspace is selected. With more than one, choose it:

```bash theme={null}
mutagent workspaces list --json
mutagent workspaces use <workspace-name>
```

## Mirror your local Helix setup

If Helix already works on your machine, copy its LLM providers:

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

The command shows what it will copy and asks before it sends anything. It then:

* copies API keys stored as plain values in your local Helix setup (`~/.mutagent/agent`),
* copies custom LLM providers and the models they declare,
* sets the workspace default model if the workspace has none. It never replaces a default.

It does not copy:

* OAuth or subscription logins. One exception: an OpenRouter permanent key saved in OAuth form is
  copied as a plain API key.
* Keys stored as references, such as `$VAR`, `${VAR}`, or `!command`. They are never evaluated.
* Your local default model.

The plan lists each LLM provider to create or update, any endpoint that changes, and anything that
blocks a copy. A copied key does not prove that the model works. To confirm it, run a task with that
model.

| Flag | What it does |
| - | - |
| `-y, --yes` | Skip the confirmation. Required when there is no terminal to ask in. |
| `--no-overwrite` | Leave LLM providers the workspace already has unchanged. |
| `--provider <id>` | Copy only this local LLM provider. Repeatable. |
| `--workspace <name-or-id>` | Copy into this workspace instead of the configured one, for this run only. |
| `--channel <stable\|rc>` | Read the `stable` (default) or `rc` Helix setup. |

In a script, run `mutagent providers mirror --json` first. Without `--yes` it writes nothing, prints
the plan, and exits with code 1. Review the plan, then run it again with `--yes --json`. Exit code 3
means you are not signed in or no workspace is set. Exit code 1 means at least one entry failed.

## Add an LLM provider directly

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

```bash theme={null}
printf %s "$ANTHROPIC_API_KEY" | mutagent providers add --provider anthropic --name "Anthropic" --api-key-stdin --json
```

`--api-key <api-key>` also works, but it puts the key on the command line. Run
`mutagent providers list --json` first to check whether the LLM provider already exists. A coding
agent confirms with the user before it adds one: the command stores a credential.

The key is tested against the LLM provider before it is saved. If the workspace has no default
model yet, adding the LLM provider sets one. An existing default is never changed. See the
[command reference](/cli/commands/providers) for every type and its flags.

## Models and the workspace default

```bash theme={null}
mutagent helix models
```

This lists every model your sessions can use, as `provider/model`, and marks the default with ★.

A run picks its model in this order:

1. `--model <provider/model>`, if you pass it. It must be in the list, or the run is refused with
   HTTP 422.
2. The workspace default.
3. Neither: the run is refused with HTTP 428 before any sandbox starts. The message says what to set
   up.

To choose the default yourself:

```bash theme={null}
mutagent helix models default <provider/model>
```

You can list fallbacks after the first ID. They are used in order when the LLM provider of an earlier
model has been deactivated. The command replaces the whole list. `--clear` removes it, after which a
run without `--model` is refused with HTTP 428.

The cloud default and your local Helix default are separate. Changing one does not change the other.

## Check that it worked

```bash theme={null}
mutagent helix models --json
```

Setup is done when `models` is not empty and `default` is a model ID, not `null`. Pass an ID from
`models[].id` to `--model`; never make one up.

## If it fails

| Exit code or error | What it means | Fix |
| - | - | - |
| Exit 3 | Not signed in, or no workspace selected. | `mutagent login`, then `mutagent workspaces use <workspace-name>`. |
| Exit 2 | Your Mutagent API key expired or is invalid. | Sign in again with `mutagent login`. |
| Exit 1 from `providers mirror` | No terminal to confirm in, or an entry failed. | Run it with `--json` to see the plan, then again with `--yes --json`. |
| Exit 1 from `providers add` | The key was refused by the LLM provider, or a flag is wrong. | Read `error` and `suggestedAction` in the `--json` output. Run `mutagent providers add --help`. |
| `mutagent helix models` lists nothing | The workspace has no active LLM provider. | Add one, as above. |

See [Errors and exit codes](/cli/errors) for every code, and
[Troubleshooting cloud runs](/helix/cloud/troubleshooting#models) for the HTTP 422 and 428 refusals.


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