Skip to main content
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).
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 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 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).