LLM provider setup

This page covers adding an LLM provider to a workspace and the exact fields each catalog entry asks for. For what LLM providers are and what uses them, see LLM providers.

Adding a provider to a workspace

An LLM provider configuration belongs to the workspace you add it in.

Open the workspace's LLM providers

Go to Configuration › LLM Providers. Every catalog entry has a card there. Check that the workspace selected in the account menu is the one you mean to configure.

Choose a catalog entry

Click Configure on the entry’s card, or Add another on a card that already has a configuration. A gateway that hosts more than one model family (Azure, Vertex) asks which family this configuration is for.

Fill in the credentials

The form asks only for the fields that entry needs — see the tables below. Give the configuration a name that will still mean something to a teammate later.

Save

Click Configure. Mutagent contacts the provider with the credential before storing it. If the provider accepts it, the configuration is saved; if not, nothing is written and the provider’s own reason is shown.

Each saved configuration shows its masked key, a Models button that lists and narrows the models it offers, and buttons to test the connection, edit it, make it the default for its provider, or remove it.

Adding a provider from the CLI

The CLI goes through the same server-side check. Before you start: install the CLI and sign in with a workspace selected. A coding agent signs in with MUTAGENT_API_KEY=<key> mutagent login --json, or runs mutagent login --browser --json and shows the printed URL to the user. The LLM provider lands in the workspace mutagent workspaces current shows; --workspace <name|id> picks another for one command.

Check what the workspace already has

mutagent providers list --json

Add the provider

Pipe the key in with --api-key-stdin, so it stays out of shell history and process lists:

printf %s "$ANTHROPIC_API_KEY" | mutagent providers add --provider anthropic --name "Anthropic" --api-key-stdin --json

--api-key <key> also works, but it puts the key on the command line. The global --api-key is your Mutagent key, not the provider’s.Success: exit code 0, and the result has "success": true, the new provider’s id and the workspaceId it landed in. If the workspace has no default model yet, adding a keyed provider sets one.

Check which models it adds

mutagent helix models --json

models[].id lists the provider/model ids cloud runs and managed agents can use.

Already signed in to providers in Helix on your machine? mutagent providers mirror --json shows a plan for copying those API keys into the workspace and sends nothing; it exits 1 until you confirm. Re-run with --yes --json to apply it. See mutagent providers.

Code (exit code)	Fix
`AUTH_REQUIRED`, `WORKSPACE_REQUIRED` (3)	Sign in, then `mutagent workspaces use <name>`.
`AUTH_EXPIRED`, `INVALID_API_KEY` (2)	Your Mutagent key expired or is wrong. Sign in again.
`MISSING_CREDENTIAL` (1)	No key was given. Pass `--api-key-stdin` (or `--service-account-key` for Vertex).
`MISSING_HOSTED_FAMILY` (1)	Azure and Vertex need `--hosted-family`.
`BASE_URL_NOT_APPLICABLE` (1)	The entry has a fixed endpoint (`zai-coding-plan`). Drop `--base-url`.
The connection test failed (1)	The provider rejected the credential. Nothing was saved. See The connection test.

Reading the field tables

Every entry stores exactly one secret. Secrets are masked on entry, encrypted at rest, and never returned by the API — reads come back with a masked value such as sk-p...4f2a. Everything else is ordinary configuration and is shown back to you as typed.

Direct entries

Seven entries talk straight to the vendor and take the same three fields. Z.AI (Coding Plan) and OpenRouter are direct too, with fewer fields; they are described after the tables.

Field	Required	Description
API key	Yes	The key issued by the provider. This is the entry’s secret.
Base URL override	No	Route requests through a proxy or a regional endpoint instead of the default one.
Model allow-list	No	Narrow the models this configuration offers. Entries outside the provider’s own policy are ignored.

Where each key comes from:

Entry	`--provider` value	API key
OpenAI	`openai`	An OpenAI API key, issued from the OpenAI platform
Anthropic	`anthropic`	An Anthropic API key, issued from the Anthropic console
Google Gemini	`google`	A Google AI Studio API key
Moonshot AI	`moonshot`	A Moonshot AI platform API key
z.ai (GLM)	`glm`	A z.ai API key
DeepSeek	`deepseek`	A DeepSeek platform API key
xAI	`xai`	An xAI API key

printf %s "$DEEPSEEK_API_KEY" | mutagent providers add --provider deepseek --name "DeepSeek" --api-key-stdin

Z.AI (Coding Plan)

For a Z.AI GLM Coding Plan subscription. It takes an API key only: the endpoint is fixed, so there is no base URL override. It offers the GLM models your plan includes.

A GLM Coding Plan key works only with the Z.AI (Coding Plan) entry. A standard z.ai key belongs in the z.ai (GLM) entry instead.

printf %s "$ZAI_API_KEY" | mutagent providers add --provider zai-coding-plan --name "Z.AI" --api-key-stdin

OpenRouter

One OpenRouter key gives your cloud runs models from many vendors through your OpenRouter account. It takes an API key from openrouter.ai and an optional model allow-list; there is no base URL override. Without an allow-list, every model your key can reach on OpenRouter is offered.

printf %s "$OPENROUTER_API_KEY" | mutagent providers add --provider openrouter --name "OpenRouter" --api-key-stdin

Custom (OpenAI- or Anthropic-compatible)

Use this for any endpoint that speaks an OpenAI- or Anthropic-compatible API — one you run, or a third party’s.

Field	Required	Description
Base URL	Yes	The endpoint serving the API.
API key	Yes	The key the endpoint expects, sent as a bearer token. This is the entry’s secret.
API format	No	The API the endpoint speaks — `openai` or `anthropic` (CLI flag `--api-format`). Defaults to OpenAI.
Model allow-list	No	Narrow the models this configuration offers.

A custom endpoint offers whatever it publishes; Mutagent applies no policy of its own to it.

printf %s "$MY_KEY" | mutagent providers add --provider custom --name "My endpoint" \
  --api-key-stdin --base-url https://models.example.com/v1 --api-format openai

The base URL must be a public address: hosts ending in .internal, .local, .localhost or .home.arpa are refused.

Gateway entries

A gateway hosts models trained by someone else, so it needs the coordinates of your deployment as well as a credential. Azure and Vertex host two families each — state which family a configuration is for, and add a second configuration for the other.

Azure

Hosts OpenAI and Anthropic models. Azure addresses a model by the name given to its deployment rather than by model ID, which is why the deployment name is required.

Field	Required	Description
Resource endpoint	Yes	The Azure resource endpoint, for example `https://my-resource.openai.azure.com`.
API key	Yes	The key issued for the Azure resource. This is the entry’s secret.
Deployment name	Yes	Azure addresses a model by the name given to its deployment, not by model ID.
API version	No	Pin the Azure API version, an ISO date optionally suffixed `-preview` (for example `2024-08-01-preview`). Defaults to the current stable version when omitted.

printf %s "$AZURE_API_KEY" | mutagent providers add --provider azure --name "Azure GPT" --api-key-stdin \
  --hosted-family openai --resource-endpoint https://my-resource.openai.azure.com --deployment-name gpt-5

--hosted-family is openai or anthropic. Add --api-version <version> to pin one.

Google Vertex

Hosts Gemini and Anthropic models. Vertex authenticates with a service-account key rather than an API key, so the JSON credential is the secret here.

Field	Required	Description
Project ID	Yes	The Google Cloud project holding the Vertex AI entitlement — 6 to 30 lowercase characters, starting with a letter.
Region	Yes	The Vertex location the models are served from, for example `us-central1` or `europe-west4`. `global` is also accepted.
Service-account credential	Yes	The service-account key JSON granting Vertex AI access to the project. This is the entry’s secret.
Model allow-list	No	Narrow the models this configuration offers.

mutagent providers add --provider vertex --name "Vertex Gemini" --hosted-family gemini \
  --project-id my-project --region us-central1 --service-account-key "$(cat service-account.json)"

--hosted-family is gemini or anthropic. Vertex takes --service-account-key, not --api-key or --api-key-stdin; an API key is refused with WRONG_CREDENTIAL_FLAG.

Vertex regions are full-word locations (europe-west4, asia-northeast1, northamerica-northeast1). They are not AWS-style region codes — eu-central-1 is not a Vertex location.

AWS Bedrock

Hosts Anthropic models. One family, so there is nothing to choose.

Field	Required	Description
Region	Yes	The AWS region the Bedrock models are invoked in, for example `us-east-1`.
Bearer API key	Yes	A Bedrock bearer API key. This is the entry’s secret, and the only credential type Bedrock accepts.
Inference profile	No	Pin a cross-region inference profile. Defaults to the profile for the configured region.

printf %s "$BEDROCK_API_KEY" | mutagent providers add --provider bedrock --name "Bedrock Claude" \
  --api-key-stdin --region us-east-1

Bedrock needs no --hosted-family.

Bedrock takes a bearer API key only. Long-lived AWS access-key credentials are not supported.An access key ID and secret access key pair — whether submitted as an AKIA… value or as ACCESS_KEY_ID:SECRET — is rejected before any connection is attempted. Issue a Bedrock API key and use that instead.

Bedrock addresses Anthropic models as region-prefixed cross-region inference profiles, such as us.anthropic.claude-opus-5-v1:0. A bare model ID without the region prefix is not a valid Bedrock target.

The connection test

Mutagent contacts the provider with the submitted credential before persisting anything. This runs on the server, so it applies to every client equally — a configuration added through the CLI is checked exactly as one added in the web app.

If the provider accepts the credential, the configuration is saved.
If it does not, nothing is written and the provider’s own error is returned. Your secret is stripped out of that message before you ever see it.

Two failures are worth recognising because they are answered before the network is touched:

No credential submitted. Mutagent never falls back to a key sitting in the environment. A blank credential fails the test rather than silently picking one up from somewhere else.
An unnamed gateway family. A gateway hosting more than one family cannot be proven against a family nobody named, so state which family the configuration targets.

To re-check a configuration that is already stored:

mutagent providers test <provider-id>

Verifying from the CLI

# List the workspace's providers
mutagent providers list

# The catalogue models for each provider type
mutagent providers list --models

# The models cloud runs can use with the workspace's active providers
mutagent helix models

# Show one provider — the key comes back masked
mutagent providers get <provider-id>

# Re-run the connection test against the live provider
mutagent providers test <provider-id>

Add --json to any of them for one JSON object on stdout. <provider-id> comes from mutagent providers list. test lists the models the provider reports and exits 0 when the connection works.

Security

Provider secrets are encrypted at rest and never returned by the API.

Each configuration holds exactly one secret, encrypted at rest.
API responses always mask it — the real value is never echoed back, not even to the person who entered it.
A configuration is reachable only from the workspace it belongs to.
Rotate keys by updating the configuration; the replacement is connection-tested like any other.

Troubleshooting

The connection test failed when I added a provider

Nothing was saved — the message shown is the provider’s own. Check that the key is current and has not been revoked, and that any endpoint, region or project field matches the deployment the key belongs to.

Bedrock rejects my AWS access key

Expected. Bedrock accepts a bearer API key only; an access key ID and secret pair is refused before a connection is attempted. Issue a Bedrock API key and submit that.

I was asked which model family my gateway configuration is for

Azure and Vertex each host two families, and one configuration covers one family. Pick the family this credential is for, then add a second configuration for the other.

A provider is missing from the CLI

Providers belong to a single workspace. Check you are pointed at the right one with mutagent workspaces current, then mutagent providers list. Switch with mutagent workspaces use <name>.

A run fails saying the model is unavailable

A gateway only offers what its hosted family offers, and a model allow-list narrows that further. Run mutagent helix models to see the model ids cloud runs can use, and pick one from that list.

Overview

Sandbox

Managed agents

Setup

LLM provider setup

Adding a provider to a workspace

Adding a provider from the CLI

Reading the field tables

Direct entries

Z.AI (Coding Plan)

OpenRouter

Custom (OpenAI- or Anthropic-compatible)

Gateway entries

Azure

Google Vertex

AWS Bedrock

The connection test

Verifying from the CLI

Security

Troubleshooting

​Adding a provider to a workspace

​Adding a provider from the CLI

​Reading the field tables

​Direct entries

​Z.AI (Coding Plan)

​OpenRouter

​Custom (OpenAI- or Anthropic-compatible)

​Gateway entries

​Azure

​Google Vertex

​AWS Bedrock

​The connection test

​Verifying from the CLI

​Security

​Troubleshooting

Adding a provider to a workspace

Adding a provider from the CLI

Reading the field tables

Direct entries

Z.AI (Coding Plan)

OpenRouter

Custom (OpenAI- or Anthropic-compatible)

Gateway entries

Azure

Google Vertex

AWS Bedrock

The connection test

Verifying from the CLI

Security

Troubleshooting