docs: update documentation for OpenHands v1.16.0

docs.json

@@ -281,6 +281,7 @@
               "openhands/usage/agent-canvas/llm-profiles",
               "openhands/usage/agent-canvas/acp-agents",
               "openhands/usage/agent-canvas/plugins",
+              "openhands/usage/agent-canvas/canvas-extensions",
               "openhands/usage/agent-canvas/critic",
               "openhands/usage/agent-canvas/customize-and-settings",
               "openhands/usage/agent-canvas/mobile-access"
@@ -314,6 +315,7 @@
           {
             "group": "Release Notes",
             "pages": [
+              "openhands/usage/agent-canvas/release-notes/v1.16.0",
               "openhands/usage/agent-canvas/release-notes/v1.15.0",
               "openhands/usage/agent-canvas/release-notes/v1.14.0",
               "openhands/usage/agent-canvas/release-notes/v1.13.0",

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

@@ -44,6 +44,12 @@
 
 An OpenHands profile references an LLM profile, so model and credential changes are managed in `Settings > LLM`. Use this when you want Agent Canvas to own both the agent behavior and the model configuration.
 
+### Let the Agent Switch LLM Profiles
+
+The OpenHands profile editor includes a **"Let the agent switch LLM profiles"** toggle. When enabled, the agent is given the `SwitchLLMTool`, which lets it switch between available LLM profiles during a conversation. When disabled, the tool is removed from the agent's toolset.
+
+This toggle is version-gated: it appears only when the connected backend reports agent-server `1.31.0` or later. On older backends (for example, agent-server `1.29.0`–`1.30.x`) the toggle is hidden.
+
 ## ACP Profiles
 
 Use an ACP profile when you want Agent Canvas to drive an external coding agent through the Agent Client Protocol.

openhands/usage/agent-canvas/canvas-extensions.mdx

@@ -0,0 +1,174 @@
+---
+title: Canvas Extensions (Beta)
+description: Add trusted custom pages and integrated tools to Agent Canvas without forking the application.
+---
+
+Canvas Extensions let you add custom pages to Agent Canvas without changing the Agent Canvas source code. An extension can provide an integrated dashboard, project tool, or other browser interface that connects to the active Agent Server.
+
+<Warning>
+  Canvas Extensions are a beta feature. The name and extension API may change as the feature develops.
+</Warning>
+
+## What Canvas Extensions Add
+
+The initial beta supports **custom pages**. When you enable an extension, its pages appear in the Agent Canvas sidebar and open inside the application.
+
+An extension page can:
+
+- Render a browser-based interface inside Agent Canvas
+- Add nested routes below its declared page path
+- Navigate to other Agent Canvas pages
+- Make authenticated HTTP requests to the active Agent Server
+- Read metadata about the extension and active backend
+
+The current beta does not support conversation tabs, arbitrary interface slots, themes, visualizer replacement, or direct Agent Server WebSocket connections.
+
+Canvas Extensions change the Agent Canvas interface. They are different from [skills](/overview/skills), which give agents instructions and knowledge, and [plugins](/openhands/usage/agent-canvas/plugins), which package agent capabilities and configuration.
+
+## Availability
+
+Canvas Extensions are managed by the active Agent Server and are currently available with supported local backends. They are not available when an OpenHands Cloud backend is active.
+
+Each backend has its own installed extensions, files, versions, and enabled states. Switching backends replaces the extensions shown in Agent Canvas.
+
+If `Customize > Extensions` reports that the feature is unavailable, update the Agent Server connected to Agent Canvas. A backend without the Canvas Extensions API cannot install or run extensions.
+
+## Install an Extension
+
+Open `Customize > Extensions`, then select `Add extension`.
+
+<Tabs>
+  <Tab title="Git Repository">
+    1. Enter the Git source, such as `github:owner/repository`.
+    2. Optionally enter a branch, tag, or commit in `Ref`.
+    3. If the extension is not at the repository root, enter its directory in `Repo path`.
+    4. Select `Add extension`.
+  </Tab>
+  <Tab title="Backend-Local Path">
+    1. Enter the absolute path to the extension directory.
+    2. Select `Add extension`.
+
+    The path is resolved on the Agent Server machine. A path on the computer running your browser will not work unless that computer also runs the Agent Server and exposes the same path.
+  </Tab>
+</Tabs>
+
+One Add extension operation installs one extension package. If a repository contains several extensions, add each manifest directory separately with its own `Repo path`.
+
+New extensions are installed **disabled**. Review the source, resolved revision, manifest details, and contributed pages before enabling one.
+
+## Enable and Manage Extensions
+
+To run an installed extension:
+
+1. Open `Customize > Extensions`.
+2. Find the installed extension and enable it.
+3. Review and accept the trusted-code notice.
+4. Open its new item in the Agent Canvas sidebar.
+
+You can disable an extension without restarting Agent Canvas. Its navigation items and mounted pages are removed immediately. Re-enable it to load the extension again, or uninstall it to remove the installation from the active backend.
+
+### Trust Model
+
+Enabling an extension runs its JavaScript in the same browser context as Agent Canvas. The beta does not isolate extensions in an iframe or worker and does not enforce fine-grained permissions.
+
+Only enable extensions whose code and resolved revision you trust. An enabled extension has the browser authority available to Agent Canvas and can use an authenticated helper to call the active Agent Server.
+
+## Build an Extension
+
+An extension is a directory containing:
+
+- `canvas-extension.json` at the extension root
+- One self-contained browser ESM entrypoint inside that root
+- Any source files or build configuration needed to produce the entrypoint
+
+The current package format uses manifest schema `1` and host API `1`.
+
+### Create the Manifest
+
+```json canvas-extension.json
+{
+  "schema_version": 1,
+  "name": "example-dashboard",
+  "display_name": "Example dashboard",
+  "version": "0.1.0",
+  "description": "A project dashboard for Agent Canvas.",
+  "entrypoint": "extension.js",
+  "contributes": {
+    "pages": [
+      {
+        "id": "dashboard",
+        "title": "Dashboard",
+        "path": "/dashboard",
+        "nav_label": "Dashboard"
+      }
+    ]
+  }
+}
+```
+
+Use lowercase letters, numbers, and hyphens for extension names and page IDs. Page paths must start with `/`, and every page ID and path must be unique within the extension.
+
+The `entrypoint` must stay inside the extension root. Bundle dependencies, CSS, and required assets into one browser ESM file; unresolved package imports and external runtime chunks cannot be loaded.
+
+### Register the Page
+
+Export an `activate` function from the entrypoint and register each page declared in the manifest:
+
+```js extension.js
+export function activate(host) {
+  if (host.apiVersion !== "1") {
+    throw new Error("This extension requires host API 1.");
+  }
+
+  return host.registerPage("dashboard", ({ container, path }) => {
+    const page = document.createElement("section");
+    page.setAttribute("aria-label", "Example dashboard");
+    page.textContent = path ? `Dashboard route: ${path}` : "Dashboard";
+    container.append(page);
+
+    return () => page.remove();
+  });
+}
+```
+
+The page ID passed to `registerPage` must match a page declared in `canvas-extension.json`. Return cleanup functions for registered pages, DOM nodes, timers, listeners, and other effects so the extension can be disabled or reloaded safely.
+
+Agent Canvas mounts this example at:
+
+```text
+/extensions/example-dashboard/dashboard
+```
+
+For a nested URL such as `/extensions/example-dashboard/dashboard/services`, the page receives `services` as its relative `path`.
+
+### Connect to the Agent Server
+
+Use `host.agentServer.request` for authenticated requests to the backend that owns the extension:
+
+```js
+const serverInfo = await host.agentServer.request({
+  method: "GET",
+  path: "/server_info",
+});
+```
+
+Request paths must be root-relative, begin with exactly one `/`, and must not be full URLs. Do not derive backend URLs or authentication credentials from Agent Canvas internals.
+
+The beta host API does not expose the backend origin or a WebSocket authentication capability. Use the authenticated HTTP helper, polling where appropriate, or a backend-owned bridge instead of opening a direct Agent Server WebSocket.
+
+## Design for the Beta Lifecycle
+
+Agent Canvas may activate, mount, and dispose an extension repeatedly when you enable or disable it, update it, reconnect, or switch backends. Extension pages should:
+
+- Render only inside the supplied page container
+- Scope styles to an extension-specific root element
+- Clean up all DOM nodes, styles, timers, listeners, observers, and subscriptions
+- Prevent late asynchronous responses from updating an unmounted page
+- Handle loading, empty, malformed-response, and error states
+- Remain keyboard accessible and usable on narrow screens
+
+## Learn More
+
+- [Canvas Extensions specification](https://github.com/OpenHands/OpenHands/blob/main/specs/canvas-extensions.md)
+- [Minimal extension fixture](https://github.com/OpenHands/OpenHands/tree/main/src/fixtures/canvas-extensions/demo-page)
+- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings)

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

@@ -15,8 +15,9 @@ Open the top-level `Customize` area to manage:
 - [MCP Servers](/openhands/usage/settings/mcp-settings)
 - [Skills](/overview/skills)
 - [Plugins](/openhands/usage/agent-canvas/plugins)
+- [Canvas Extensions (Beta)](/openhands/usage/agent-canvas/canvas-extensions)
 
-Use the section navigation inside `Customize` to switch between these pages.
+Use the section navigation inside `Customize` to switch between these pages. Canvas Extensions add trusted custom pages to Agent Canvas, while skills and plugins change agent behavior.
 
 <Note>
   MCP Server configuration lives under `Customize > MCP Servers`, not under `Settings`.

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.
 
@@ -51,6 +51,8 @@
 
 The setup screen defaults to `OpenHands` as the provider and pre-selects a recommended model. Switch the `LLM Provider` dropdown to choose a different provider.
 
+The default model is **OpenAI GPT-5.6 Sol**, and **DeepSeek V4 Flash** is the free OpenHands-routed model. When adding an OpenHands provider connection, the provider field is a searchable supported-provider selector rather than free text.
+
 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.
 
 ## Step 4: Start From a Proven Workflow
@@ -68,7 +70,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.
 
 ## Getting Started Checklist
 
@@ -77,7 +79,7 @@
 1. **Set up your LLM** — links to `Settings > LLM`
 2. **Connect MCP servers** — links to `Customize > MCP`
 3. **Start a conversation** — links to `Conversations`
 4. **Explore automations** — links to `Automate`
 5. **Customize your agent** — links to `Customize`
 6. **Review settings** — links to `Settings`
 

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

@@ -38,11 +38,11 @@
 2. In the **Basic** tab, select `OpenHands`, choose a model, and add the key.
 3. Save the profile and start a new conversation.
 
-While using OpenHands as your LLM provider you will see OpenHands-routed model IDs as marked as`Free`. These models change as we have promotional periods where we can offer them without any additional token cost.
+While using OpenHands as your LLM provider you will see OpenHands-routed model IDs marked as `Free`. These models change as we have promotional periods where we can offer them without any additional token cost. Currently **DeepSeek V4 Flash** is the free OpenHands-routed model.
 
 The `Free` label applies only to those full `openhands/` routes. Endpoints from other providers with similar model names may have separate billing. The label remains visible after you select one of these models.
 
-When you create a local LLM profile, the form initially selects `openhands/kimi-k3` and derives the profile name `kimi-k3`. You can change either value before saving.
+When you create a local LLM profile, the form initially selects **OpenAI GPT-5.6 Sol** (the default model) and derives the profile name from it. You can change either value before saving.
 
 For key details and available models, see [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms).
 
@@ -54,7 +54,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.
 
@@ -64,7 +64,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
 
@@ -84,7 +84,9 @@
 
 1. Open `Settings > LLM`.
 2. In the **Provider Connections** panel, add a new connection.
-3. Enter a name, the provider, the API key, and an optional base URL.
+3. Enter a name, then select a provider from the searchable supported-provider selector, and add the API key and an optional base URL.
+
+The provider field in the **create** connection flow is a searchable selector backed by the supported-provider catalog. You must select a supported provider before the connection can be saved. Existing connections retain free-text editing, so legacy or custom provider identifiers remain maintainable.
 
 ### Link a Profile to a Provider Connection
 
@@ -131,7 +133,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/managing-automations.mdx

@@ -1,17 +1,17 @@
 ---
 title: Managing automations
 description: Browse, export, import, enable, disable, and run automations from the Agent Canvas Automate view.
 ---
 
 The **Automate** view in Agent Canvas is the in-app control center for your automations. From here you can see all automations on the active backend, inspect their configuration and run history, and manage their lifecycle without leaving the app.
 
 <Note>
   Automations run on the active backend. Switch backends from [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) to see automations on a different backend.
 </Note>
 
 ## Browse and inspect automations
 
 Open the **Automate** tab in the sidebar to see all automations on the active backend. Each row shows the automation name, trigger type, and enabled state. When the active backend is healthy but has no automations, the Automate pane remains available and includes an option to add one.
 
 Click an automation to open its detail view. The detail view shows:
 
@@ -24,15 +24,19 @@
 
 A run can be `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, or `SKIPPED`. A `SKIPPED` run can occur when the backend reaches its concurrency limit. Future backend statuses appear as a neutral status badge so they do not prevent you from viewing the automation.
 
+### Run Phase
+
+Automation runs surface a live **phase** that reflects a run's current state: `PENDING`, `RUNNING`, or `FAILED`. The phase appears on automation cards, in the Activity Log, and on the home screen, and updates live as a run progresses. A failed run retains its last phase after it stops.
+
 ### Activity Log Costs and Exports
 
 The Activity Log displays a completed run's reported LLM cost in USD to four decimal places. A measured zero cost appears as `$0.0000`; when the backend does not report a cost, no cost appears in the log.
 
-Use the Activity Log export controls to download run data as CSV or JSON. Both formats include a raw numeric `cost` field for every run. An unavailable cost is exported as `null`.
+Use the Activity Log export controls to download run data as CSV or JSON. Both formats include a raw numeric `cost` field for every run, as well as the run's `phase`. An unavailable cost is exported as `null`.
 
 ## Enable and disable automations
 
 Toggle an automation on or off from the kebab menu (⋮) on the automation row, or from the detail view. Disabled automations do not fire on their scheduled trigger or in response to events, but their configuration is preserved.
 
 ## Run an automation manually
 
@@ -95,7 +99,7 @@
 
 5. Confirm to create the automation.
 
 Imported automations are created **disabled**. After importing, open the automation from the list, review its configuration, and enable it when ready.
 
 ## Related guides
 

openhands/usage/agent-canvas/release-notes/v1.16.0.mdx

@@ -0,0 +1,36 @@
+---
+title: Agent Canvas 1.16.0
+description: Release notes for Agent Canvas version 1.16.0
+---
+
+# Agent Canvas 1.16.0
+
+Released August 27, 2026.
+
+[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.16.0).
+
+## Highlights
+
+- **Supported-provider selector** — The "Add provider" connection flow now uses a searchable supported-provider selector instead of free text. Existing connections keep free-text editing.
+- **Linux desktop installer** — New Linux desktop installer artifacts (AppImage and deb) for the Agent Canvas desktop app.
+- **Live run phase for automations** — Automation runs now surface a live phase (PENDING/RUNNING/FAILED) on cards, the activity log, and home; the phase is exported in CSV/JSON activity logs.
+- **LLM-switching toggle in Agent settings** — A new "Let the agent switch LLM profiles" toggle in the Agent profile editor controls whether the `SwitchLLMTool` is available to the agent.
+- **Explicit skill allow-list** — The skill catalog now defaults to an 11-skill allow-list instead of enabling all ~59 catalog skills; Customize gains a "Recommended" badge/facet.
+- **Canvas Extensions beta** — Add trusted custom pages and integrated tools to Agent Canvas without forking the application. Install and manage extensions in `Customize > Extensions`; see [Canvas Extensions (Beta)](/openhands/usage/agent-canvas/canvas-extensions).
+
+## Improvements and fixes
+
+- File paths in chat are now clickable and link to the Files drawer.
+- Onboarding is skipped when a user-added Local backend already has a usable LLM.
+- The default model is now OpenAI GPT-5.6 Sol, and DeepSeek V4 Flash is the sole free OpenHands-routed model.
+- The VSCode button now renders on self-hosted (local) backends, gated on editor capability.
+- The API key for the OpenHands provider is hidden on cloud.
+- The home screen remembers local workspace mode selection.
+- Conversation titles can be renamed on cloud backends.
+- The API key is validated before advancing the backend connection step.
+- Routine dependency bumps (software-agent-sdk 1.44.0, automation 1.9.0, extensions 0.19.0).
+
+## Full changelog
+
+- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.16.0)
+- [Compare v1.15.0 to v1.16.0](https://github.com/OpenHands/OpenHands/compare/v1.15.0...v1.16.0)

openhands/usage/agent-canvas/setup.mdx

@@ -3,10 +3,10 @@
 description: Install, run, update, or uninstall Agent Canvas.
 ---
 
 The `agent-canvas` launcher can run the Canvas client with Agent Server, Automation Server, and ingress as an all-in-one local stack. Use npm or npx for direct local execution, or Docker for a containerized stack with explicit project mounts. You can also run the client separately and connect it to an existing backend.
 
 <Warning>
   Treat agents and ACP processes as untrusted: they can run shell commands, read files, write files, and use connected tools within their execution environment. Agent Canvas is the client and does not provide isolation. If the backend runs directly on your machine, the agent can act with your user account's permissions. Use a container, sandbox, or VM to define a tighter boundary. Before exposing backend services to a network you do not control, review [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm).
 </Warning>
 
 ## Choose An Install Method
@@ -15,12 +15,12 @@
 |--------|-------------|---------------------------|
 | **npm local install** | You want the quickest local browser setup. | Runs directly on your machine and can work in local workspaces you open. |
 | **Docker** | You want a local sandbox with clearer file boundaries. | Runs inside a container and can access mounted project directories. |
 | **npx** | You want to try Agent Canvas without installing the package globally. | Runs directly on your machine and can work in local workspaces you open. |
 | **VM / self-hosted** | You want an always-on backend, stronger hardware, or a team-accessible server. | Runs on the VM or dedicated host you configure. |
 | **From source** | You are contributing to Agent Canvas or changing the frontend/backend stack. | Runs your local development checkout. |
 
 <Note>
   If you are new to Agent Canvas, use `npx` for a quick first run or npm local install if you want a reusable `agent-canvas` command. Use Docker when you specifically want sandboxing.
 </Note>
 
 ## Verify Prerequisites
@@ -65,7 +65,7 @@
 </Tabs>
 
 <Note>
   Termux and other mobile Linux environments are not a primary supported target. For the most reliable local setup, use macOS, Linux, Windows with PowerShell, or Windows with WSL2.
 </Note>
 
 ## Install And Run
@@ -121,7 +121,7 @@
       PowerShell uses backticks (`` ` ``) for line continuation. If Docker reports that it cannot connect to the daemon, start Docker Desktop and run the command again.
     </Note>
   </Tab>
     <Tab title="npx">
     Run the latest published package without installing it globally:
 
     ```bash
@@ -308,7 +308,7 @@
 
 ## Desktop App (Preview Build)
 
-The Agent Canvas desktop app for macOS and Windows is an early preview build ready for user testing. It bundles the Node.js and `uv` runtimes, so you do not need to install prerequisites or keep a terminal open.
+The Agent Canvas desktop app for macOS, Windows, and Linux is an early preview build ready for user testing. It bundles the Node.js and `uv` runtimes, so you do not need to install prerequisites or keep a terminal open.
 
 <Note>
   Please [join the OpenHands Slack community](https://openhands.dev/joinslack) to share feedback and [open an issue](https://github.com/OpenHands/OpenHands/issues) for problems you find while testing the preview.
@@ -332,6 +332,12 @@
 2. Run the installer. If Windows SmartScreen prompts you, confirm that you want to continue.
 3. Launch Agent Canvas from the Start menu.
 
+**Linux**
+
+1. Download the `Agent-Canvas-<version>.AppImage` or `Agent-Canvas-<version>.deb` installer.
+2. For the AppImage, make the file executable and run it. For the deb, install it with your package manager (for example, `sudo apt install ./Agent-Canvas-<version>.deb`).
+3. Launch Agent Canvas from your applications menu.
+
 The desktop app starts its local backend automatically. During startup, select **Show details** to view and copy the live startup log. This is useful if startup takes longer than expected or fails.
 
 ### Troubleshooting and Lifecycle

overview/skills.mdx

@@ -117,6 +117,8 @@ In the SDK, explicitly supplied skills override automatically loaded user and pu
 
 In Agent Canvas, disabling a bundled or custom skill prevents it from being included in the agent context for new OpenHands and ACP conversations. Enabled skills remain available to new conversations.
 
+The skill catalog defaults to an **explicit allow-list** of recommended skills rather than enabling every available skill. The `Customize > Skills` page shows the full catalog with a **Recommended** badge and facet; only the recommended skills are enabled by default. You can enable any additional skill individually. An existing deny-list still takes precedence over the default allow-list.
+
 See [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) for Agent Canvas and [Plugin Launcher](/openhands/usage/cloud/plugin-launcher) for loading a Git-hosted skill into an OpenHands Cloud conversation.
 
 <Warning>