Skip to main content
This page covers adding a provider to a workspace and the exact fields each catalog entry asks for. For the model behind it — one level, attached to the workspace — see the providers overview.

​
Adding a provider to a workspace

A provider configuration belongs to the workspace you add it in. There is no level to pick.
1

Open the workspace's providers

Go to Settings → Workspace → Providers. Confirm the workspace named there is the one you mean to configure.
2

Choose a catalog entry

Select Add provider and pick the entry. Selecting a gateway that hosts more than one model family (Azure, Vertex) asks which family this configuration is for.
3

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

Save

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.
The same is available from the CLI, which goes through the same server-side check:

​
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. All of them take the same three fields. Where each key comes from:

​
Custom (OpenAI-compatible)

Use this for any endpoint that speaks an OpenAI-compatible API — one you run, or a third party’s. A custom endpoint offers whatever it publishes; Mutagent applies no policy of its own to it.

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

​
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.
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.
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 dashboard.
  • 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:

​
Verifying from the CLI

​
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

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.
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.
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.
Providers belong to a single workspace. Check you are pointed at the right one with mutagent config list, then mutagent providers list.
A gateway only offers what its hosted family offers, and a model allow-list narrows that further. Run mutagent providers list --models to see what the configuration actually offers.