Skip to main content
Preview — local backends only. Provider connections are available on local agent-server backends only; the section does not appear on cloud backends. Cloud support is planned. UI labels and the flow may still change (see OpenHands/OpenHands#15492).
A provider connection is a small, named bundle of the credential material an LLM profile would otherwise carry inline: an API key and a base URL. Instead of pasting the same key into every profile that uses a provider, you save it once as a connection and link your profiles to it. Rotating the key is then a single edit that every linked profile picks up on its next run.

​
Where to find it

Open Settings > LLM. On a local agent-server, the Provider connections section appears below the list of LLM profiles. (On cloud backends the section is hidden.)

​
Add a connection

  1. In the Provider connections section, choose Add connection.
  2. Fill in the form:
    • Name — the display name shown on the connection row (required).
    • Provider — a free-text provider identifier. Defaults to custom; set it to something like openai or anthropic when you want the row to say so.
    • API key — the key issued by that provider or gateway (required when creating a connection).
    • Base URL — OpenAI-compatible endpoint, for example https://api.openai.com.
  3. Save. The connection appears as a row showing its name, provider, the number of profiles linked to it, and an indicator of whether a key is set.
The API key is encrypted at rest on the backend (the same cipher machinery LLM profiles use) and is never returned to the UI — the row only reports whether a key is set. Provider connections are consumed from the LLM profile form. When you create or edit a profile on a local backend, a Provider connection dropdown lets you point the profile at a saved connection:
  • When a profile is linked, its inline API key and Base URL inputs are hidden — the profile reads both from the connection at runtime.
  • Choose None in the dropdown to unlink the profile and go back to entering a key and base URL directly on the profile.
Several profiles can link to the same connection, so a set of profiles that all use one provider share a single key.

​
Edit a connection or rotate its key

Use the edit (pencil) control on a connection row to change its name, provider, or base URL, or to rotate the key. The key field follows the same “blank means unchanged” convention as the profile form: leave it empty to keep the stored key, or type a new value to rotate it. Every linked profile uses the updated connection on its next run — there is nothing to re-enter per profile.

​
Delete a connection

Use the delete (trash) control on a connection row and confirm. If any LLM profiles still reference the connection, the backend refuses the delete and names the profiles that must be unlinked first, so a key in use is never removed out from under a profile.

​
Provider connections vs. LLM profiles

Provider connections do not replace profiles — a profile still selects the exact model for a conversation. A connection just lets several profiles share one key instead of each storing its own.

​
Not in the preview

The following are not part of this preview:
  • Cloud backends — the section is local-agent-server only for now.
  • Provider presets, wire-API selection, and custom headers — the form is a name, a free-text provider, a key, and a base URL.
  • Multiple keys per connection — a connection holds a single key.