diff --git a/docs.json b/docs.json index d2eff8ac..0e3b3c47 100644 --- a/docs.json +++ b/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", diff --git a/openhands/usage/agent-canvas/agent-profiles.mdx b/openhands/usage/agent-canvas/agent-profiles.mdx index 9785fa06..bb639cdc 100644 --- a/openhands/usage/agent-canvas/agent-profiles.mdx +++ b/openhands/usage/agent-canvas/agent-profiles.mdx @@ -44,6 +44,12 @@ Use an OpenHands profile when you want Agent Canvas to run the built-in OpenHand 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. diff --git a/openhands/usage/agent-canvas/canvas-extensions.mdx b/openhands/usage/agent-canvas/canvas-extensions.mdx new file mode 100644 index 00000000..9377b2b5 --- /dev/null +++ b/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. + + + Canvas Extensions are a beta feature. The name and extension API may change as the feature develops. + + +## 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`. + + + + 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`. + + + 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. + + + +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) diff --git a/openhands/usage/agent-canvas/customize-and-settings.mdx b/openhands/usage/agent-canvas/customize-and-settings.mdx index 6d624de5..aa74a80b 100644 --- a/openhands/usage/agent-canvas/customize-and-settings.mdx +++ b/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. MCP Server configuration lives under `Customize > MCP Servers`, not under `Settings`. diff --git a/openhands/usage/agent-canvas/first-time-setup.mdx b/openhands/usage/agent-canvas/first-time-setup.mdx index cc66103b..1ef20ca2 100644 --- a/openhands/usage/agent-canvas/first-time-setup.mdx +++ b/openhands/usage/agent-canvas/first-time-setup.mdx @@ -51,6 +51,8 @@ Available options: 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 diff --git a/openhands/usage/agent-canvas/llm-profiles.mdx b/openhands/usage/agent-canvas/llm-profiles.mdx index ce83066a..beed1581 100644 --- a/openhands/usage/agent-canvas/llm-profiles.mdx +++ b/openhands/usage/agent-canvas/llm-profiles.mdx @@ -38,11 +38,11 @@ Use an OpenHands LLM API key when you want Agent Canvas to access models through 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). @@ -84,7 +84,9 @@ When you want multiple LLM profiles to share the same provider credentials, use 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 diff --git a/openhands/usage/agent-canvas/managing-automations.mdx b/openhands/usage/agent-canvas/managing-automations.mdx index e9ddd781..3dd836dd 100644 --- a/openhands/usage/agent-canvas/managing-automations.mdx +++ b/openhands/usage/agent-canvas/managing-automations.mdx @@ -24,11 +24,15 @@ Click an automation to open its detail view. The detail view shows: 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 diff --git a/openhands/usage/agent-canvas/release-notes/v1.16.0.mdx b/openhands/usage/agent-canvas/release-notes/v1.16.0.mdx new file mode 100644 index 00000000..ae9cea48 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/openhands/usage/agent-canvas/setup.mdx b/openhands/usage/agent-canvas/setup.mdx index 2b845a1d..05ba5193 100644 --- a/openhands/usage/agent-canvas/setup.mdx +++ b/openhands/usage/agent-canvas/setup.mdx @@ -308,7 +308,7 @@ Uninstalling the package or image does not automatically remove your persisted d ## 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. 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 @@ Pre-built desktop releases support Apple silicon Macs. On an Intel Mac, use the 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-.AppImage` or `Agent-Canvas-.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-.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 diff --git a/overview/skills.mdx b/overview/skills.mdx index 78a5e4f4..0526cf44 100644 --- a/overview/skills.mdx +++ b/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.