> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-docs-provider-connections.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Model providers

> Connect an LLM provider once with a single API key, then add and manage the models under it — no need to paste the key into every model.

<Note>
  **Preview — local backends only.** This feature is currently available on
  **local agent-server backends**. Cloud support is planned. UI labels and the
  flow are subject to change while the feature is in review
  (see [OpenHands/OpenHands#15492](https://github.com/OpenHands/OpenHands/issues/15492)).
</Note>

Model providers reduce the repeated setup that comes with entering the same key
for every model. Instead of pasting an API key into each model configuration,
you add a **provider** once with a single key, then curate the models under it.
Every model nested under the provider shares that provider's key and endpoint,
so adding another model from the same provider takes no key re-entry.

GitHub Copilot appears as a managed provider when it is available from your
GitHub account. It is read-only — it does not require an API key or extra
configuration, and its models follow your Copilot subscription.

## How it works

1. Open `Settings > Model providers` and choose **Add provider**.
2. Pick a provider from the preset list (Custom endpoint, OpenAI, Anthropic,
   Azure OpenAI, Foundry Local, Microsoft Foundry, and others). Use the search
   box to filter.
3. Fill in the provider form:
   * **Display name** — the name shown on the provider card.
   * **Base URL** — the OpenAI-compatible root for the provider or gateway,
     for example `https://api.openai.com/v1`.
   * **Wire API** — the wire format the endpoint speaks: `Auto`,
     `Chat Completions`, or `Responses`. Individual models can override this.
   * **API key** — the key issued by that provider or gateway. It is stored in
     your OS keychain and never written to the database.
   * **Custom headers (JSON)** — optional object of extra HTTP headers, such as
     `{"X-Org": "eng"}`.
4. Save the provider. It appears as a card in the **Configured providers** list.

The key is stored as a **named secret** on the backend and is **never returned**
to the UI — the provider card only reports whether a key is set. The provider
record stores non-secret endpoint settings (base URL, wire API, custom headers)
alongside a reference to the secret. Rotating the key later is a single update
that every model under the provider picks up automatically.

## Manage models under a provider

Each provider card lists the models you have added under it. Because the key and
endpoint live on the provider, managing models never asks for the key again:

* **Add model** — use the `+` affordance on the provider to add a model by name
  (for example `gpt-5.6-luna`). Optionally set a per-model **Wire API** override
  when a single model speaks a different format than the provider default.
* **Edit model** — rename a model or change its per-model wire-API override.
* **Remove model** — delete an individual model row from the provider.

Models are a curated list you manage directly. Optionally, **Test** a provider
to probe its stored key; on success it can suggest catalog models as a
convenience for the **Add model** step. Testing never changes the models you
have already curated.

## Edit a provider or rotate its key

Use the **edit** (pencil) control on a provider card to change its display name,
base URL, wire API, or custom headers, or to rotate the key. Rotating the key
updates the single named secret, so every model under the provider uses the new
key on its next run — there is nothing to re-enter per model.

## Remove a provider

Use the **delete** (trash) control on a provider card and confirm to remove the
provider. This deletes the provider record, its nested models, and the named
secret that held its key.

## Model providers vs. LLM Profiles

|             | Model provider                                       | LLM Profile                                |
| ----------- | ---------------------------------------------------- | ------------------------------------------ |
| Holds a key | Yes (once, as a named secret shared by its models)   | Yes (per profile)                          |
| Scope       | A provider and the models curated under it           | A single model configuration               |
| Purpose     | Add a provider once, then add/edit/remove its models | Pick the specific model for a conversation |

Model providers sit alongside the LLM Profiles list in
`Settings > Model providers`. They do not replace profiles — a profile still
selects the exact model for a conversation. A provider lets you establish the
key once so every model under it can reuse it.

## Availability and follow-ups

The following are **not** part of the preview and will arrive in follow-up
releases:

* **Cloud backends** — the page is available on local agent-server backends;
  the `deploy` app-server mirror for cloud is planned.
* **Background catalog refresh** — an automatic, periodic refresh of a
  provider's advertised models.
* **Multiple keys per provider** — holding more than one key on the same
  provider (for example, separate work and personal keys).

## Related

* [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles)
* [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings)
* [First Time Setup](/openhands/usage/agent-canvas/first-time-setup)
* [Secrets Settings](/openhands/usage/settings/secrets-settings)