Docs: Provider connections page + cross-links (preview, local-only) (#15492)

docs.json

@@ -262,6 +262,7 @@
           "openhands/usage/agent-canvas/setup",
           "openhands/usage/agent-canvas/first-time-setup",
           "openhands/usage/agent-canvas/llm-profiles",
+          "openhands/usage/agent-canvas/provider-connections",
           "openhands/usage/agent-canvas/conversations",
           "openhands/usage/agent-canvas/agent-profiles",
           "openhands/usage/agent-canvas/plugins",

openhands/usage/agent-canvas/customize-and-settings.mdx

@@ -56,7 +56,7 @@ The `Settings` area currently includes the following sections:
 | `Application` | UI-level preferences and app behavior |
 | `Secrets` | Stored secrets used by the active backend |
 
-On local backends, the `LLM` page also includes an `Available Profiles` area for saved profiles.
+On local backends, the `LLM` page also includes an `Available Profiles` area for saved profiles, and a **Provider connections** section for saving one API key once and sharing it across several profiles (see [Provider connections](/openhands/usage/agent-canvas/provider-connections), preview).
 
 In `Settings > Application`, the **Conversation titles** setting selects the LLM profile used to generate conversation titles. **Automatic** uses the active local LLM profile; you can choose another saved profile, like a small, cheap LLM, when you want titles generated independently from the model selected for agent work. The same page shows the installed Agent Canvas version, update availability, and a **Check for updates** button.
 

openhands/usage/agent-canvas/first-time-setup.mdx

@@ -12,7 +12,7 @@
 Agent Canvas uses the **Agent-Client Protocol (ACP)** to communicate with agents, which means you're not locked into a single provider.
 
 - **OpenHands** (selected by default) — the general-purpose OpenHands agent, best for coding and exploration.
 - **Claude Code** — Anthropic's Claude Code agent.
 - **Codex** — OpenAI's Codex agent.
 - **Gemini CLI** — Google's Gemini CLI agent.
 
@@ -53,6 +53,13 @@
 
 For OpenHands Agent Profiles, this LLM setup becomes the model profile the agent uses. ACP agents such as Claude Code, Codex, and Gemini CLI use their own authentication and model configuration.
 
+<Note>
+To reuse one API key across several profiles instead of pasting it into each
+one, save it once as a provider connection from `Settings > LLM`. See
+[Provider connections](/openhands/usage/agent-canvas/provider-connections)
+(preview, local backends).
+</Note>
+
 ## Step 4: Start From a Proven Workflow
 
 ![Agent Canvas first-time setup — Say hello screen showing pre-built workflow templates including GitHub PR review copilot, GitHub repository monitor, and Slack standup digest](/openhands/static/img/agent-canvas-setup-step-4.png)
@@ -68,7 +75,7 @@
 - **GitHub Repository Monitor** — watch a repository for `@OpenHands` mentions and respond automatically.
 - **Slack Standup Digest** — summarize yesterday's Slack activity into an async standup note.
 
 You can browse all pre-built automations from the `Automate` view at any time. See [Pre-built Automations](/openhands/usage/agent-canvas/prebuilt-automations) for the full list.
 
 ## After Your First Session
 

openhands/usage/agent-canvas/llm-profiles.mdx

@@ -5,6 +5,13 @@
 
 Agent Canvas supports configuring your LLM provider, model, and credentials from the UI. It also supports saved **LLM profiles**, which make it easier to switch models without re-entering provider settings each time.
 
+<Note>
+To reuse a single API key across several profiles instead of pasting it into
+each one, save it once as a provider connection and link your profiles to it.
+See [Provider connections](/openhands/usage/agent-canvas/provider-connections)
+(preview, local backends).
+</Note>
+
 LLM profiles can also generate conversation titles. In `Settings > Application > Conversation titles`, leave the selection on **Automatic** to use the active local profile, or select a saved profile dedicated to title generation.
 
 ## Configure an LLM Profile
@@ -42,7 +49,7 @@
 
 ### Local OpenAI-Compatible Endpoint
 
 A local server can be LM Studio, Ollama, vLLM, SGLang, or another service that exposes an OpenAI-compatible API. In the **Advanced** tab, enter the provider, exact model ID, endpoint base URL, and the required API key or a placeholder value when the server does not require one.
 
 The URL must be reachable from the **backend**, not only from your browser. For example, a backend in Docker cannot use `127.0.0.1` to reach a model server running on the host. Use the host address appropriate for that backend and confirm the endpoint's model inventory before saving.
 
@@ -52,7 +59,7 @@
 - **Base URL**: `http://host.docker.internal:1234/v1`
 - **API key**: `local-llm` or another placeholder value when the server does not require authentication
 
 See [Local LLMs](/openhands/usage/llms/local-llms) for LM Studio, Ollama, and other local-server examples.
 
 ### LiteLLM Proxy
 
@@ -93,7 +100,7 @@
 |---|---|---|
 | Provider is not recognized | Provider selection and model prefix | Use the matching configuration path above. |
 | Model format or identifier error | Exact model ID | Compare it with the provider or proxy model inventory. |
 | Local server cannot be reached | Base URL from the backend | Check host, port, and container or network reachability. |
 | Authentication or permission error | Key type and backend scope | Re-enter the key or follow the provider guide. |
 | Model cannot perform the task | Context and tool support | Choose a compatible model from the provider's recommendations. |
 

openhands/usage/agent-canvas/provider-connections.mdx

@@ -0,0 +1,99 @@
+---
+title: Provider connections
+description: Store one API key (and optional base URL) as a named provider connection, then link multiple LLM profiles to it so they share the key.
+---
+
+<Note>
+  **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](https://github.com/OpenHands/OpenHands/issues/15492)).
+</Note>
+
+A **provider connection** is a small, named bundle of the credential material an
+LLM profile would otherwise carry inline: an **API key** and an optional **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** — optional OpenAI-compatible endpoint, for example
+     `https://api.openai.com`. Leave it blank to use the provider's default.
+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.
+
+## Link a profile to a connection
+
+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 connection | LLM profile |
+|---|---|---|
+| Holds a key | Yes — one key (and optional base URL) shared by linked profiles | Yes — inline, unless linked to a connection |
+| Scope | Reusable credential referenced by id | A single, selectable model configuration |
+| Purpose | Store one key once and share it | Pick the exact model for a conversation |
+
+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 an optional base URL.
+- **Multiple keys per connection** — a connection holds a single key.
+
+## 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)

openhands/usage/settings/llm-settings.mdx

@@ -6,7 +6,7 @@
 ## Overview
 
 The LLM settings allows you to bring your own LLM and API key to use with OpenHands. This can be any model that is
 supported by litellm, but it requires a powerful model to work properly.
 [See our recommended models here](/openhands/usage/llms/llms#model-recommendations). You can also configure some
 additional LLM settings on this page.
 
@@ -50,6 +50,13 @@
 This is useful when you want to use different models for different tasks—for example, a faster model for simple tasks
 and a more powerful model for complex reasoning.
 
+<Note>
+To reuse a single API key across several profiles instead of pasting it into
+each one, save it once as a provider connection and link your profiles to it.
+See [Provider connections](/openhands/usage/agent-canvas/provider-connections)
+(preview, local backends).
+</Note>
+
 ### Creating an LLM Profile
 
 Profiles are automatically created when you save a configuration on the LLM settings page. To create a new profile:
@@ -166,7 +173,7 @@
 Implement a simple web page on the features of OpenHands with Claude Opus 4.7, and then switch to GPT-5.5 and review the code.
 ```
 
 ![Agent Canvas showing example switch_llm tool calls that move a task between saved profiles](/openhands/static/img/model-selection-tool-agent-canvas.png)
 
 The model selection tool behaves as follows: