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

# Connect a Provider

> Connect an LLM vendor once with a single API key, then reuse the connection across models — no need to paste the key into every profile.

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

Provider Connections reduce the repeated setup that comes with per-model LLM
profiles. Instead of pasting the same API key into every profile you create, you
connect a vendor **once** with one key. OpenHands validates the key against the
provider's catalog and stores it as a named secret. You can then reuse the
connection across models from that provider.

## How it works

1. Open `Settings > LLM` and choose **Connect a Provider**.
2. Select a vendor (Anthropic, OpenAI, Google, or another supported provider).
3. Paste the API key issued by that provider. Add an optional label to tell
   connections apart when you have more than one key for the same vendor.
4. OpenHands tests the key (when the key field loses focus, or via **Test
   connection**) and, on success, shows the models it grants.
5. Pick which models to make available. Models marked **Recommended** are
   pre-selected; use **Select all** or expand **More from {vendor}** for the
   rest. Each selected model becomes an LLM profile that shares this
   connection's key.
6. The connection appears in the **Provider Connections** list, where you can
   **Refresh**, **Rotate key**, or **Disconnect** it later.

The key is stored as a named secret on the backend and is **never returned** to
the UI — the connection only reports whether a key is set. Rotating a key later
updates the secret that every profile created from the connection references.

## Provider Connections vs. LLM Profiles

|                 | Provider Connection                  | LLM Profile                                |
| --------------- | ------------------------------------ | ------------------------------------------ |
| Holds a key     | Yes (stored once as a secret)        | Yes (per profile)                          |
| Tied to a model | No — covers the whole vendor catalog | Yes                                        |
| Purpose         | Reuse one key across many models     | Pick the specific model for a conversation |

Provider Connections sit **above** the LLM Profiles list in `Settings > LLM`.
They do not replace profiles — a profile still selects the exact model for a
conversation. A connection lets you establish the key once so profiles that use
the same vendor can reuse it.

## Refresh and update the catalog

Select **Refresh** on a connection to re-test the key against the provider's
catalog. This pulls the current model list on demand; OpenHands does not run a
background refresh job in this release. Refreshing after a provider adds new
models makes them available when you next connect or re-pick from that provider.

If the key no longer works, the connection shows the error returned by the
provider (for example, an expired or revoked key). Use **Rotate key** to update
the key without removing the connection — every profile created from the
connection picks up the new key automatically.

## Remove a connection

Select **Disconnect** on a connection and confirm to remove it. Profiles that
referenced the connection's key will need a new key before they can authenticate
again — OpenHands warns you when a removed connection still has profiles pointing
at it.

## Availability and follow-ups

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

* **Cloud backends** — the section is hidden on cloud until the `deploy`
  app-server mirror lands.
* **Background catalog refresh** — an automatic periodic refresh of the model
  list (today this is pull-on-demand via **Refresh**).
* **Multiple keys per provider** — connecting more than one key to the same
  vendor (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)