From 274ab318a567612aa7a44535572b1c45b6c09e2a Mon Sep 17 00:00:00 2001 From: enyst <6080905+enyst@users.noreply.github.com> Date: Mon, 14 Sep 2026 03:10:16 +0000 Subject: [PATCH] docs: sync llms context files --- llms-full.txt | 5753 ++++++++++++++++++++++++++++++++++++++++++++++--- llms.txt | 37 +- 2 files changed, 5505 insertions(+), 285 deletions(-) diff --git a/llms-full.txt b/llms-full.txt index 32c7d659..03396b24 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -37,7 +37,7 @@ Get started with some examples or keep reading to learn more. icon="plug" href="/sdk/guides/agent-server/openai-gateway" > - Access the OpenHands agent via an OpenAI-compatible endpoint for chat UIs, IDEs, voice platforms, and other OpenAI-style clients. + Access the OpenHands agent via OpenAI-compatible Chat Completions and Responses endpoints for chat UIs, IDEs, voice platforms, and other OpenAI-style clients. @@ -6311,7 +6311,7 @@ For full list of implemented workspaces, see the [source code](https://github.co **Features:** - REST API & WebSocket endpoints for conversations, bash, files, events, desktop, and VSCode -- [OpenAI-compatible `/v1/chat/completions` endpoint](/sdk/guides/agent-server/openai-gateway) for clients that expect an OpenAI-style backend +- [OpenAI-compatible `/v1/chat/completions` and `/v1/responses` endpoints](/sdk/guides/agent-server/openai-gateway) for clients that expect an OpenAI-style backend - Service management with isolated per-user sessions - API key authentication and health checking @@ -9216,6 +9216,185 @@ On the agent-server side, the ACP-capable REST surface lives under `/api/acp/con - **[TaskToolSet](/sdk/guides/task-tool-set)** — Compose multiple agents for complex workflows - **[LLM Metrics](/sdk/guides/metrics)** — Track token usage and costs across models +### Ask Oracle +Source: https://docs.openhands.dev/sdk/guides/agent-ask-oracle.md + +import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx"; + +> A ready-to-run example is available [here](#ready-to-run-example)! + +Use `ask_oracle` when an agent should consult a stronger or more specialized +model for a second opinion without switching its active model. + +## When to Use It + +`ask_oracle` is useful when an agent is: + +- Stuck or uncertain about its next step +- Comparing implementation approaches +- Reviewing a risky or difficult decision +- Asked by the user to get a second opinion + +## How It Works + +When the agent calls `ask_oracle`: + +1. The tool loads the saved LLM profile named `oracle`. +2. The Oracle receives a dedicated system prompt and a user message containing + the agent's question and optional context. +3. The Oracle returns a text recommendation to the original agent. +4. The original agent continues the conversation with its existing model. + +The Oracle does not receive the conversation history or any tools. It cannot +modify the workspace directly. Its token usage and cost are included in the +conversation's combined metrics. + + + The tool does not fall back to the agent's active model. If the `oracle` + profile is missing or cannot be loaded, the tool returns an error observation + telling the agent that the Oracle is unavailable. + + +## Configure the Oracle Profile + +The tool resolves its model by convention from a saved LLM profile named +`oracle`. There is no dedicated agent setting for selecting another profile. + +To enable it: + +1. Save a usable LLM configuration under the name `oracle`. See + [LLM Profile Store](/sdk/guides/llm-profile-store). +2. Add `AskOracleTool` to the agent's tools: + +```python icon="python" wrap focus={2, 5} +from openhands.sdk import Agent, Tool +from openhands.tools.ask_oracle import AskOracleTool + +agent = Agent( + llm=primary_llm, + tools=[Tool(name=AskOracleTool.name)], +) +``` + +By default, `LocalConversation` reads profiles from +`~/.openhands/profiles`. If you use a custom profile directory, pass the same +directory to both `LLMProfileStore` and `LocalConversation` through +`profile_store_dir`. + + + Do not place literal API keys in source code. The ready-to-run example reads + its key from the environment and stores the Oracle profile in a temporary + directory, which is removed after the example exits. Follow the + [LLM Profile Store](/sdk/guides/llm-profile-store) guidance when creating a + persistent profile. + + +## Ask Oracle vs. Switch LLM + +`ask_oracle` makes one stateless call to another model and then returns control +to the original agent. It never changes the active conversation model. + +Use `switch_profile()` or the `switch_llm` tool instead when subsequent agent +turns should run on a different saved profile. See +[LLM Profile Store](/sdk/guides/llm-profile-store#mid-conversation-model-switching). + +## Ready-to-run Example + + +This example is available on GitHub: [examples/01_standalone_sdk/58_ask_oracle_tool/main.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/58_ask_oracle_tool/main.py) + + +```python icon="python" expandable examples/01_standalone_sdk/58_ask_oracle_tool/main.py +"""Consult the Oracle end-to-end with the ask_oracle tool. + +The Oracle is a saved LLM profile resolved by convention under the name +``oracle``. This example wires two profiles — the agent's primary model and a +separate ``oracle`` model — adds ``Tool(name="ask_oracle")`` to the agent, then +drives a normal conversation: the agent decides to call ``ask_oracle``, the tool +consults the ``oracle`` profile, and the agent uses the Oracle's answer to reply. + +Usage: + LLM_API_KEY=... LLM_BASE_URL=https://llm-proxy.app.all-hands.dev \ + uv run python examples/01_standalone_sdk/58_ask_oracle_tool/main.py + +Note: + The example saves the ``oracle`` profile in a temporary directory so it + does not modify the user's default profile store. +""" + +import os +import tempfile + +from pydantic import SecretStr + +from openhands.sdk import LLM, Agent, LocalConversation, Tool +from openhands.sdk.llm.llm_profile_store import LLMProfileStore +from openhands.tools.ask_oracle import ORACLE_PROFILE_NAME, AskOracleTool + + +DEFAULT_BASE_URL = "https://llm-proxy.app.all-hands.dev" +# The agent's primary model (follows the standard LLM_MODEL env like other +# examples). The Oracle defaults to the same model; override ASK_ORACLE_MODEL to +# point the "oracle" profile at a different/stronger model. +PRIMARY_MODEL = os.getenv("ASK_ORACLE_PRIMARY_MODEL") or os.getenv( + "LLM_MODEL", "openai/gpt-5.5" +) +ORACLE_MODEL = os.getenv("ASK_ORACLE_MODEL", PRIMARY_MODEL) + +api_key = os.getenv("LLM_API_KEY") +assert api_key is not None, "LLM_API_KEY environment variable is not set." +base_url = os.getenv("LLM_BASE_URL", DEFAULT_BASE_URL) + +with tempfile.TemporaryDirectory() as profile_store_dir: + store = LLMProfileStore(profile_store_dir) + store.save( + ORACLE_PROFILE_NAME, + LLM( + model=ORACLE_MODEL, + api_key=SecretStr(api_key), + base_url=base_url, + usage_id="oracle", + ), + include_secrets=True, + ) + + primary_llm = LLM( + model=PRIMARY_MODEL, + api_key=SecretStr(api_key), + base_url=base_url, + usage_id="primary", + ) + agent = Agent(llm=primary_llm, tools=[Tool(name=AskOracleTool.name)]) + conversation = LocalConversation( + agent=agent, + workspace=os.getcwd(), + profile_store_dir=profile_store_dir, + ) + + print(f"Primary model: {conversation.agent.llm.model}") + print(f"Oracle model: {ORACLE_MODEL}") + conversation.send_message( + "Call the oracle to ask it for its opinion on the weather today, " + "then just tell me in two words how it's like." + ) + conversation.run() + + cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost + print(f"Total cost: ${cost:.6f}") + print(f"EXAMPLE_COST: {cost}") +``` + + + +## Next Steps + +- **[LLM Profile Store](/sdk/guides/llm-profile-store)** - Create and manage + reusable LLM configurations +- **[LLM Metrics](/sdk/guides/metrics)** - Track usage and cost across the + primary and Oracle models +- **[Custom Tools](/sdk/guides/custom-tools)** - Build tools with custom + behavior + ### Browser Use Source: https://docs.openhands.dev/sdk/guides/agent-browser-use.md @@ -12628,10 +12807,24 @@ Source: https://docs.openhands.dev/sdk/guides/agent-server/openai-gateway.md import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx"; -The agent-server exposes an OpenAI-compatible `/v1/chat/completions` endpoint so clients that already speak the OpenAI protocol can call an OpenHands agent. +The agent-server exposes an OpenAI-compatible API surface under `/v1` with two endpoints: + +- `POST /v1/chat/completions` — the OpenAI Chat Completions protocol. +- `POST /v1/responses` — the OpenAI Responses protocol. Use this when you want an existing chat UI, IDE integration, evaluation harness, voice platform, or another agent to treat OpenHands as an OpenAI-style backend while still getting the full agent runtime behind the request. +## How It Works + +Both endpoints are protocol adapters over the **same full OpenHands agent**, not a thin wrapper around a raw LLM call. Each request: + +1. Loads the OpenHands agent configured by the named profile. +2. Starts (or, for Chat Completions, optionally reuses) an OpenHands conversation. +3. Runs the agent's complete internal tool loop to completion. +4. Returns only the final assistant text as an OpenAI-shaped response. + +The mental model is **"access an agent conversation as if it were a model"**: you send a prompt, the agent does its work (including executing tools in its workspace), and you receive one response when it finishes. Internal tool activity is not exposed as OpenAI tool calls. + ## What to Configure Most OpenAI-compatible clients ask for the same three fields: @@ -12644,11 +12837,13 @@ Most OpenAI-compatible clients ask for the same three fields: For example, a saved LLM profile named `gateway_demo` appears as the OpenAI model `openhands_gateway_demo`. -The gateway accepts the same session key in either OpenHands or OpenAI-compatible form: +Authentication maps OpenAI-style bearer tokens onto the agent-server's existing session key mechanism. The gateway accepts the same session key in either form: - `X-Session-API-Key: ` - `Authorization: Bearer ` +Both are validated against the configured session API keys — there is no second credential system. When the server is configured without session keys, it remains unauthenticated just like the native agent-server API. + ## Prepare a Profile OpenAI-compatible traffic is backed by an agent-server LLM profile. Create one with the native profile API first: @@ -12678,7 +12873,19 @@ curl "$AGENT_SERVER_URL/v1/models" \ -H "Authorization: Bearer $SESSION_API_KEY" ``` -## Client Recipes +## Chat Completions (`POST /v1/chat/completions`) + +Each request runs a full OpenHands agent to completion and returns the final assistant text in a standard Chat Completions shape. + +Supported request fields: + +- `model` — required; must be an `openhands_` exposed via `GET /v1/models`. +- `messages` — a standard list. The last `user` message becomes the agent's task; `system` and `developer` messages are folded into the agent's system context. +- `stream` — `true` returns a server-sent events stream; `false` (default) returns a single response. + +The response includes a `X-OpenHands-ServerConversation-ID` header. Send that header on a follow-up request to continue the same server-side OpenHands conversation instead of starting a new one. + +### Client Recipes @@ -12780,7 +12987,6 @@ For Open WebUI, LibreChat, Chatbot UI, and similar OpenAI-compatible frontends, - **Base URL**: `https://YOUR_AGENT_SERVER/v1` - **API key**: your agent-server session API key - **Model**: `openhands_` -- **Streaming**: disabled for now If the UI can store a response header and send a custom request header, persist `X-OpenHands-ServerConversation-ID` per chat thread and send it on follow-up turns. If it cannot, each request starts a new OpenHands conversation and works best for one-shot tasks. @@ -12817,9 +13023,9 @@ Return `reply_text` to the voice or webhook platform. Keep the mapping for as lo -## Conversation State +### Conversation State -The OpenAI Chat Completions protocol usually sends full message history on every request. The OpenHands gateway does not reconstruct agent history from prior assistant messages. Instead: +The Chat Completions protocol usually sends full message history on every request, but the gateway does **not** reconstruct agent history from prior assistant messages. Instead: - Omit `X-OpenHands-ServerConversation-ID` to start a new OpenHands conversation. - Read `X-OpenHands-ServerConversation-ID` from the response. @@ -12827,11 +13033,128 @@ The OpenAI Chat Completions protocol usually sends full message history on every When reusing a conversation, send the newest user turn in `messages`. The server-side OpenHands conversation owns the previous agent state, tool activity, and workspace context. -## Current Limitations +## Responses (`POST /v1/responses`) + +The Responses endpoint targets the OpenAI Responses API — a better fit for agent-shaped traffic, with typed input/output items. It is **stateless-first** by design. + +### Mental Model + +Every request starts a **fresh** OpenHands conversation and runs the full agent to completion. There is no server-side continuation handle: to carry context forward, clients replay prior input and output items into the next request's `input`. + +```bash +curl "$AGENT_SERVER_URL/v1/responses" \ + -H "Authorization: Bearer $SESSION_API_KEY" \ + -H "Content-Type: application/json" \ + -d "{ + \"model\": \"$OPENHANDS_MODEL\", + \"instructions\": \"Answer briefly.\", + \"input\": \"Summarize this repository in one sentence.\", + \"store\": false + }" +``` + +Response: + +```json +{ + "id": "resp_…", + "object": "response", + "created_at": 1726000000.0, + "completed_at": 1726000120.0, + "model": "openhands_gateway_demo", + "instructions": "Answer briefly.", + "output": [ + { + "id": "msg_…", + "type": "message", + "role": "assistant", + "status": "completed", + "content": [ + { "type": "output_text", "text": "This repository is …", "annotations": [] } + ] + } + ], + "parallel_tool_calls": false, + "previous_response_id": null, + "status": "completed", + "tool_choice": "none", + "tools": [], + "usage": { + "input_tokens": 123, + "input_tokens_details": { "cached_tokens": 0 }, + "output_tokens": 45, + "output_tokens_details": { "reasoning_tokens": 0 }, + "total_tokens": 168 + } +} +``` + +The response also carries the `X-OpenHands-ServerConversation-ID` header, but unlike Chat Completions you **cannot** pass it back to continue that conversation — the Responses surface ignores it. Use the header only to correlate the response with the underlying OpenHands conversation through the native agent-server API. + +### Replaying Context + +To maintain context across Responses calls, replay the previous assistant output items (and any system/developer context) into the next request's `input`: -- Only non-streaming Chat Completions requests are supported. Requests with `stream: true` return `400` until streaming support is added. -- The response contains the final assistant text only. Internal OpenHands tool activity is not exposed as OpenAI tool calls. -- OpenAI request fields that are not needed by the gateway are ignored or rejected intentionally by the server implementation. +```python +import os +from typing import cast + +from openai import OpenAI +from openai.types.responses import ResponseInputItemParam + +client = OpenAI( + api_key=os.environ["SESSION_API_KEY"], + base_url=f"{os.environ['AGENT_SERVER_URL']}/v1", +) + +first = client.responses.create( + model=os.environ["OPENHANDS_MODEL"], + instructions="You are reviewing this repository.", + input="Summarize the project structure.", + store=False, +) + +second = client.responses.create( + model=os.environ["OPENHANDS_MODEL"], + input=[ + {"role": "developer", "content": "You are reviewing this repository."}, + {"role": "user", "content": "Summarize the project structure."}, + *[ + item.model_dump(mode="json", exclude_none=True) + for item in cast(list[ResponseInputItemParam], first.output) + ], + {"role": "user", "content": "Now list the main packages."}, + ], + store=False, +) +``` + +### How Input Is Interpreted + +- Top-level `instructions` and any `system`/`developer` input items become the agent's **system context**. +- The remaining input items become the agent's user prompt. A single `user` item is sent as-is; multiple non-system items are wrapped in `` tags so their roles are preserved. +- `model` must be an `openhands_` exposed via `GET /v1/models`. + +### Not Supported Yet + +The following OpenAI Responses features are intentionally rejected or ignored. Status codes and wording are exact. + +| Feature | Behavior | +| --- | --- | +| `previous_response_id` | Rejected with `400` — `"previous_response_id is not supported; replay input items instead"`. | +| `store: true` | Rejected with `400` — `"Persistent response storage (store=True) is not supported yet"`. There is no retrievable Responses object and no `GET /v1/responses/{id}`. | +| `stream: true` | Rejected with `400` — `"Streaming responses are not supported yet"`. | +| `tools`, `tool_choice`, `parallel_tool_calls` | Accepted but **ignored** — the caller's declared tools do not replace OpenHands' internal tool loop. | +| `temperature` and other generation-tuning fields | Accepted but **ignored**. | + + +Setting `store: false` (the default) is **not** a data-retention control. It only signals that no Responses object is retained. The backing OpenHands conversation still follows the agent-server's normal persistence policy. + + +## Current Limitations (Both Endpoints) + +- The response contains the final assistant text only. Internal OpenHands tool activity is not exposed as OpenAI tool calls or Responses output items. +- OpenAI request fields the gateway does not need are either ignored or rejected intentionally by the server implementation. Declared tools and generation-tuning fields do not change agent behavior. ## Ready-to-run example @@ -13031,7 +13354,7 @@ A Remote Agent Server is an HTTP/WebSocket server that: - **Manages workspaces** (Docker containers or remote sandboxes) - **Streams events** to clients via WebSocket - **Handles command and file operations** (execute command, upload, download), check [base class](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/base.py) for more details -- **Accepts OpenAI-compatible Chat Completions requests** through the [OpenAI-compatible endpoint](/sdk/guides/agent-server/openai-gateway) +- **Accepts OpenAI-compatible Chat Completions and Responses requests** through the [OpenAI-compatible endpoint](/sdk/guides/agent-server/openai-gateway) - **Provides isolation** between different agent executions Think of it as the "backend" for your agent, while your Python code acts as the "frontend" client. @@ -13210,6 +13533,39 @@ This is useful when: - Letting users edit agent configuration in a form-based UI - Rehydrating the same agent setup in another process +## Load Persisted Settings + +`model_validate` only accepts payloads that already match the current schema. Use `from_persisted` for data written by an older SDK version: it applies the registered schema migrations first, then validates the migrated payload against the class you call it on. + +```python icon="python" focus={1} +restored = OpenHandsAgentSettings.from_persisted(payload) +``` + +`from_persisted` is defined on `AgentSettingsBase`, so it is a concrete-variant loader: `OpenHandsAgentSettings.from_persisted()` returns an `OpenHandsAgentSettings` and `ACPAgentSettings.from_persisted()` returns an `ACPAgentSettings`. When you do not know which variant a payload holds, use `validate_agent_settings` (also in `openhands.sdk.settings`) instead — it dispatches across the settings union. + +Passing an already-validated instance of that variant returns it unchanged, so its secrets are preserved without a lossy serialization round trip. + + +The deprecated `agent_kind="llm"` discriminator is only rewritten while migrating between schema versions. A payload that is already at the current schema version but still carries `agent_kind="llm"` is therefore rejected by `OpenHandsAgentSettings.from_persisted`. Load those payloads with `validate_agent_settings`, which canonicalizes the discriminator unconditionally. + + +### Encrypted Payloads + +Secret-bearing fields only decrypt when you pass the same validation context that was used to write them. + +```python icon="python" focus={2} +persisted = settings.model_dump(mode="json", context={"cipher": cipher}) +restored = OpenHandsAgentSettings.from_persisted(persisted, context={"cipher": cipher}) +``` + +### Errors + +| Exception | Raised when | +|-----------|-------------| +| `TypeError` | The payload is not a mapping or `BaseModel`, or its `schema_version` is not an integer. | +| `ValueError` | `schema_version` is negative, newer than the supported version, or has no registered migration. | +| `pydantic.ValidationError` | The migrated payload is invalid for the class you called `from_persisted` on. | + ## Create an Agent from Settings Once validated, create a working agent directly from the settings object. @@ -18191,9 +18547,9 @@ Hooks let you observe and customize key lifecycle moments in the SDK without for ## Exit Codes -Command hooks (shell scripts) signal their result through their exit code — -[agent-based hooks](#agent-based-hooks) return a JSON decision instead. The SDK -matches the +Command hooks (shell scripts) signal their result through their exit code. +[Prompt-based hooks](#prompt-based-hooks) and +[agent-based hooks](#agent-based-hooks) return a JSON decision instead. The SDK matches the [Claude Code hook contract](https://docs.claude.com/en/docs/claude-code/hooks): - **`0` — success.** The operation proceeds. `stdout` is parsed as JSON for @@ -18218,6 +18574,20 @@ policy must exit with `2`. - Isolation: hooks run outside the agent loop logic, avoiding core modifications - Composition: enable or disable hooks per environment (local vs. prod) +## Execution Modes + +Hook definitions support three execution modes: + +| `type` | Evaluator | Tool access | Best for | +|--------|-----------|-------------|----------| +| `command` (default) | Shell command | Through the script | Deterministic checks and integrations | +| `prompt` | One LLM completion | No | Semantic decisions based only on the hook event | +| `agent` | Short-lived sub-agent | Optional allowlist | Decisions that require workspace investigation | + +Use the least powerful mode that can make the decision. Command hooks are the +most deterministic. Prompt hooks add model judgment with one completion. Agent +hooks add an agent loop and tools when the event payload is not enough. + ## Ready-to-run Example @@ -18458,6 +18828,149 @@ exit 0 +## Prompt-based Hooks + +Set `type="prompt"` to evaluate a hook event with one LLM completion. Prompt +hooks are useful when a decision needs semantic judgment but all required +context is already present in the `HookEvent` payload. For example, a +`PreToolUse` policy can evaluate the intent of a terminal command without +starting a tool-using sub-agent. + +```python +HookDefinition( + type=HookType.PROMPT, + name="terminal-safety", + prompt="Deny terminal commands that recursively delete files ...", + timeout=30, +) +``` + +Key fields on a prompt `HookDefinition`: + +- `name` — identifies the hook in logs, events, and its stable + `prompt-hook:` metrics bucket. +- `prompt` — the trusted policy used to evaluate each matching event. +- `timeout` — the timeout applied to the copied hook LLM. + +The hook uses the conversation's current LLM, including changes made through +model or profile switching. The executor copies that LLM so the hook has an +isolated timeout, usage ID, and metrics. Hook spend is merged back into the +parent conversation's metrics. The SDK selects Chat Completions or the Responses +API from the model's capabilities. Prompt hooks are single-shot and non-streaming, +regardless of the parent LLM's streaming setting. + +The policy is placed in system context. The serialized event is sent in a +separate user message and marked as untrusted data, so instructions embedded in +tool input or output are not treated as hook policy. The model is asked to +return the shared hook result contract: + +```json +{"decision": "allow" | "deny", "reason": ""} +``` + +If the conversation has no LLM, the provider call fails, or the response does +not contain a valid decision, the hook falls open with `decision="allow"` and +`success=False`. This lets consumers distinguish an execution failure from a +deliberate allow verdict. + + +Prompt hooks cannot inspect files, run commands, or access conversation history +beyond data included in the hook event. Use an [agent-based hook](#agent-based-hooks) +when the evaluator must gather more context before deciding. + + + +This example is available on GitHub: [examples/01_standalone_sdk/57_prompt_hooks](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/57_prompt_hooks/) + + +```python icon="python" expandable examples/01_standalone_sdk/57_prompt_hooks/main.py +"""OpenHands Agent SDK - prompt-based hooks example. + +Evaluates two synthetic PreToolUse events with one LLM completion each. The +commands are only event data: this example never executes them. +""" + +import os +import tempfile +from pathlib import Path + +from pydantic import SecretStr + +from openhands.sdk import LLM +from openhands.sdk.conversation.conversation_stats import ConversationStats +from openhands.sdk.hooks import ( + HookConfig, + HookDefinition, + HookManager, + HookMatcher, + HookType, +) + + +api_key = os.getenv("LLM_API_KEY") +assert api_key is not None, "LLM_API_KEY environment variable is not set." + +llm = LLM( + usage_id="agent", + model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"), + base_url=os.getenv("LLM_BASE_URL"), + api_key=SecretStr(api_key), +) + +TERMINAL_POLICY = """Evaluate the semantic intent of a terminal command. +Deny commands that recursively delete files, read credentials or sensitive +system files, modify the host system, or exfiltrate data. Allow read-only +workspace inspection, builds, and test commands. When uncertain, deny and give +a concise reason.""" + +hook_config = HookConfig( + pre_tool_use=[ + HookMatcher( + matcher="terminal", + hooks=[ + HookDefinition( + type=HookType.PROMPT, + name="terminal-safety", + prompt=TERMINAL_POLICY, + timeout=30, + ) + ], + ) + ] +) + +cases = [ + ("python -m pytest -q", True), + ("find / -type f -delete", False), +] + +with tempfile.TemporaryDirectory() as tmpdir: + stats = ConversationStats() + manager = HookManager( + config=hook_config, + working_dir=str(Path(tmpdir)), + session_id="prompt-hook-example", + llm=llm, + conversation_stats=stats, + ) + + for command, expected_to_continue in cases: + should_continue, results = manager.run_pre_tool_use( + tool_name="terminal", + tool_input={"command": command}, + ) + result = results[0] + verdict = "ALLOW" if should_continue else "DENY" + print(f"{verdict:5} {command}") + print(f" {result.reason}") + assert should_continue is expected_to_continue + + cost = stats.get_combined_metrics().accumulated_cost + print(f"\nEXAMPLE_COST: {cost}") +``` + + + ## Agent-based Hooks Besides shell scripts, a hook can delegate its decision to an LLM-driven @@ -25801,6 +26314,56 @@ agent_context = AgentContext(skills=list(skills.values())) - **[MCP Integration](/sdk/guides/mcp)** - Connect external tool servers - **[Confirmation Mode](/sdk/guides/security)** - Add execution approval +### Structured Output +Source: https://docs.openhands.dev/sdk/guides/structured-output.md + +import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx"; + +Pass a Pydantic model (or a JSON Schema dict) as a tool's `response_schema`. Its fields are merged into the schema the LLM sees, so the model must populate them when it calls that tool, and the reply is validated on receipt — no prompting for a format, no output parsing. + +```python +class ProjectFacts(BaseModel): + description: str = Field(description="One-paragraph description of the project.") + facts: list[str] = Field(description="Three concise, distinct facts.") + + +agent = Agent( + llm=llm, + tools=[Tool(name="FinishTool", params={"response_schema": ProjectFacts})], +) +``` + +The tool keeps its own arguments — `FinishTool` still takes `message`, now alongside `description` and `facts`. This works on any tool, including [custom](/sdk/guides/custom-tools) and [MCP](/sdk/guides/mcp) tools. + +## Reading results + +Resolved tools live on `agent.tools_map`. Use `parse_last_response()` for the most recent call, or `parse_response(action)` for a specific one: + +```python +finish_tool = agent.tools_map["finish"] +facts = cast(ProjectFacts | None, finish_tool.parse_last_response(conversation.state.events)) +``` + +`parse_last_response()` returns `None` if the tool has not been called. With a JSON Schema dict instead of a model, both methods return a validated `dict`. + + +`parse_last_response()` re-reads the tool call, so it works after a conversation is persisted and reloaded. `action.structured_output` is in-memory only — it is not serialized with the event and comes back `None` after a round-trip, so prefer the parse methods. + + +## Constraints + +- **Reserved names.** A schema may not declare `kind`, `security_risk`, `structured_output`, or `summary`, nor reuse one of the tool's own field names (e.g. `message` on `FinishTool`). Both raise a `ValueError` when the tool is resolved. +- **One tool per spec.** A spec that resolves to a tool set is rejected; attach the schema to the individual tool instead. +- **Scoped to its tool.** A model may try to send the schema fields when calling *other* tools; those calls are rejected as unexpected arguments and the agent retries. + +## Ready-to-run Example + +```python icon="python" expandable examples/01_standalone_sdk/56_structured_output.py +# content is auto-synced +``` + + + ### Task Tool Set Source: https://docs.openhands.dev/sdk/guides/task-tool-set.md @@ -29002,6 +29565,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. @@ -29030,7 +29599,7 @@ If you choose OpenHands, the setup flow also configures the LLM profile that the ### Agent Canvas Architecture Source: https://docs.openhands.dev/openhands/usage/agent-canvas/architecture.md -Agent Canvas is the open-source browser client and control center for OpenHands conversations and automations. It presents backend state and sends requests to backend services; it is not an agent runtime or sandbox. Agent Server or an ACP agent process executes tools, and the selected workspace or sandbox provides the execution boundary. +Agent Canvas is the open-source browser client and control center for OpenHands conversations and automations. It presents backend state and sends requests to backend services; it is not an agent runtime or sandbox. Agent Server or an ACP agent CLI executes tools, and the selected workspace or sandbox provides the execution boundary. ## Core Components @@ -29041,39 +29610,10 @@ Agent Canvas is the open-source browser client and control center for OpenHands | **Automation Server** | Stores schedules and event triggers, tracks runs, and dispatches conversations | [`OpenHands/automation`](https://github.com/OpenHands/automation) | | **Workspace or sandbox** | Defines which files, processes, credentials, and networks an agent can access | Deployment-specific | -Sandbox Server is a community-driven standalone API and sandbox control plane. It is not a core Agent Canvas backend or a supported deployment option. [Learn more about Sandbox Server](https://github.com/OpenHands/sandbox-server). +Sandbox Server is a community-driven standalone API and sandbox control plane. [Learn more about Sandbox Server](https://github.com/OpenHands/sandbox-server). ## Service Relationships -```mermaid -%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 45}} }%% -flowchart TB - Browser["Browser"] --> Canvas["Agent Canvas
browser client"] - - subgraph Backend["Selected backend"] - AgentServer["Agent Server"] -->|execute agent and tools| Workspace["Workspace or sandbox"] - Automation["Automation Server"] -->|dispatch conversation| AgentServer - end - - Canvas -->|conversations and settings| AgentServer - Canvas -->|schedules, events, and runs| Automation - - subgraph Platform["OpenHands Cloud or Enterprise"] - ControlPlane["Platform control plane"] -->|create and manage| Sandbox["Conversation sandbox"] - Sandbox -->|hosts| PlatformAgentServer["Agent Server"] - end - - Canvas -.->|managed backend| PlatformAgentServer - - classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px - classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px - classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px - classDef service fill:#e9f9ef,stroke:#2f855a,stroke-width:2px - class Canvas primary - class AgentServer,Automation,PlatformAgentServer secondary - class Workspace,Sandbox tertiary - class ControlPlane service -``` The normal browser path is **Browser → Agent Canvas → selected backend**. Agent Server owns conversation execution. Automation Server owns scheduled and event-driven run lifecycle. A backend distribution can expose both services behind one URL, but they remain separate responsibilities. @@ -29096,17 +29636,16 @@ The launcher supports split modes: Docker and Helm packages can also bundle the client and backend services. A bundled deployment changes how services are installed, not which component owns execution or isolation. -## Execution And Isolation +## Execution and Isolation When you send a message, Agent Canvas sends it to the selected backend. Agent Server starts or resumes the conversation, runs the selected agent, invokes tools, updates backend state, and streams events to Canvas. The workspace determines the execution boundary: -| Workspace type | Execution and isolation boundary | -|----------------|----------------------------------| -| **Local process** | Agent Server and tools run directly on the backend host without container isolation. | +| Execution environment | Execution and isolation boundary | +|-----------------------|----------------------------------| +| **Host process** | Agent Server and tools run directly on the backend host without container isolation. If the backend is remote, that host—not the browser's machine—is the execution boundary. | | **Docker or Kubernetes** | Agent Server and tools run inside the configured container or pod with its mounts and network policy. | -| **Remote Agent Server** | Agent Server runs on another machine or in a separate container, with the workspace boundary configured there. | | **OpenHands Cloud or Enterprise** | The managed platform creates and operates the conversation sandbox that hosts Agent Server. | Connecting Canvas to a remote backend does not grant the browser direct access to that backend's filesystem. Canvas displays files and terminal output returned by Agent Server. @@ -29127,14 +29666,14 @@ Switching backends changes which backend-managed conversations, settings, automa | Pattern | Relationship | |---------|--------------| | **Local all-in-one** | The launcher starts Canvas and local backend services on one machine. | -| **Remote Agent Server** | Canvas connects to an Agent Server running on another machine or in a separate container on the same machine. | -| **Self-hosted backend services** | You deploy Agent Server, and optionally Automation Server, on a VM, Docker host, Kubernetes cluster, or Modal. | +| **Self-hosted backend services** | You deploy Agent Server, and optionally Automation Server, in another process, on a VM, in Docker or Kubernetes, or on Modal. Canvas connects to the deployment as a remote backend. | | **Managed platform** | Canvas connects to OpenHands Cloud or OpenHands Enterprise, which operate their backend and sandbox infrastructure. | ## Next Steps - [Install Agent Canvas](/openhands/usage/agent-canvas/setup) - [Connect And Manage Backends](/openhands/usage/agent-canvas/backends) +- [Connect To A Remote Backend](/openhands/usage/agent-canvas/backend-setup/remote) - [Self-Host On A VM](/openhands/usage/agent-canvas/backend-setup/vm) - [Use Docker](/openhands/usage/agent-canvas/backend-setup/docker) - [Agent Server Overview](/sdk/guides/agent-server/overview) @@ -29151,6 +29690,7 @@ A Cloud backend is a good fit when you want to: - Run agents without tying up local resources - Use OpenHands Cloud's managed sandboxes and integrations - Keep your local machine for development while offloading agent work +- Easy Phone & Tablet Access so you can code on the go ## Prerequisites @@ -29237,11 +29777,60 @@ Configuration is passed via `-e` flags on `docker run`: | `PORT` | Ingress port inside the container (default `8000`). Map it with `-p :`. | | `LOCAL_BACKEND_API_KEY` | API key for the server. Auto-generated and persisted if not set. | | `OH_SECRET_KEY` | Secret used to protect stored settings and secrets. | +| `AGENT_CANVAS_DISABLE_TELEMETRY` | Set to `1` or `true` to disable Agent Canvas product telemetry. | + +You can also pass `--disable-telemetry` to the Agent Canvas runtime. Use the environment variable for deployment configuration because older images ignore an unknown environment variable but reject an unknown runtime flag. The agent server can execute arbitrary shell commands inside the container. If exposing it beyond localhost, set `LOCAL_BACKEND_API_KEY` to a strong secret. +## Let the Agent Use Docker + +By default the agent cannot run containers: `docker` is installed in the image, but the +daemon cannot start inside an unprivileged container. If the agent tries, it fails with +`error creating default "bridge" network: operation not permitted`. + +That matters for tasks where a container is part of the workflow — building a `Dockerfile` +and running it to confirm the change works, bringing up a `docker compose` stack to +reproduce a bug, or using a toolchain that is only published as an image. Without a +daemon the agent can edit those files but cannot verify them. + +To enable it, start the container with `--privileged`: + +```bash +docker run -it --rm \ + --privileged \ + -p 8000:8000 \ + -v ~/.openhands:/home/openhands/.openhands \ + -v ~/projects:/projects \ + ghcr.io/openhands/agent-canvas:latest +``` + + + `--privileged` gives the container broad access to the host kernel, which substantially + weakens the isolation between the agent and your machine. The agent can execute + arbitrary shell commands, so grant this only on a host you are willing to expose and + only when the agent genuinely needs to run containers. + + +Verify from inside the container: + +```bash +docker exec -it docker info +``` + + + There is no safer middle ground. The Docker daemon needs kernel capabilities that are + granted by the host when the container starts, so they cannot be acquired later — and + rootless Docker does not avoid this: the daemon starts, but containers it creates fail + to launch (`error mounting "proc" to rootfs: operation not permitted`). + + OpenHands Enterprise solves this differently, running each sandbox under a hardened + runtime that provides kernel-level isolation so nested containers run unprivileged. See + [Running Docker in the Agent Sandbox](/enterprise/docker-in-sandbox). + + ## Connect from the Frontend Start the frontend separately and point it at the container: @@ -29265,6 +29854,120 @@ Then add the Docker backend: - [Local Backend](/openhands/usage/agent-canvas/backend-setup/local) - [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) - [Kubernetes (Helm)](/openhands/usage/agent-canvas/backend-setup/kubernetes) +- [Running Docker in the Agent Sandbox](/enterprise/docker-in-sandbox) — how Enterprise does this without `--privileged` + +### Isolate Tool Execution with Docker +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/docker-execution.md + +Use Docker execution mode when you want Agent Canvas and Agent Server to remain trusted host processes while isolating filesystem and process tools in a separate container for each conversation. + +This mode differs from [running the entire Agent Canvas distribution in Docker](/openhands/usage/agent-canvas/backend-setup/docker). The outer Agent Server retains conversation state, LLM calls, credentials, policy, persistence, and orchestration. Supported tool actions run inside an ephemeral execution container. + +## Prerequisites + +- Docker installed and running on the Agent Server host +- Permission for the user running `agent-canvas` to invoke Docker +- An Agent Server image compatible with the installed Agent Server version + +## Start Agent Canvas + +Set the execution runtime and image before starting Agent Canvas: + +```bash +export OH_EXECUTION_RUNTIME=docker +export OH_EXECUTION_IMAGE=ghcr.io/openhands/agent-server:latest-python +export OH_EXECUTION_PLATFORM=linux/amd64 +agent-canvas +``` + +Use `linux/arm64` for an ARM host such as Apple Silicon. + +You can combine these variables with other launcher options. For example, to use another port: + +```bash +OH_EXECUTION_RUNTIME=docker \ +OH_EXECUTION_IMAGE=ghcr.io/openhands/agent-server:latest-python \ +OH_EXECUTION_PLATFORM=linux/amd64 \ +agent-canvas --port 9000 +``` + +The launcher forwards the variables to the local Agent Server. No separate frontend configuration is required. + +## How Isolation Works + +For each local conversation, Agent Server creates a `DockerExecutionWorkspace` with `/workspace` as its working directory. The container starts lazily when the conversation first invokes a supported tool. + +The following built-in tools execute in the container: + +- `terminal` +- `file_editor` +- `grep` +- `glob` +- `apply_patch` + +The outer Agent Server continues to run the agent loop and all LLM requests. It sends supported tool actions to an authenticated execution-only endpoint in the container. The inner server does not expose conversation, profile, settings, LLM, persistence, or WebSocket APIs. + + + Tools without a Docker execution adapter continue to run in the outer Agent Server process. Review custom and additional tools before treating the container as their security boundary. + + +## Keep the Sandbox Ephemeral + +By default, the execution container has no host filesystem mounts. Leave `OH_EXECUTION_VOLUMES` unset to keep the workspace ephemeral and prevent host files from appearing under `/workspace`. + +To mount data deliberately, provide a JSON array of Docker volume specifications: + +```bash +export OH_EXECUTION_VOLUMES='["/path/on/host:/workspace/project"]' +``` + + + A volume gives tools in the container access to the mounted host path. Do not configure volumes when you require a disposable sandbox with no host filesystem access. + + +The execution container: + +- Publishes its API only on host loopback. +- Receives a generated per-workspace capability instead of the outer server's credentials. +- Is removed when its workspace closes. +- Does not store the outer conversation state or LLM configuration. + +Conversation history persists in the outer Agent Server according to its normal persistence configuration. Files created only inside an unmounted execution container do not persist after that container is removed. + +## Verify Isolation + +Create a new conversation and ask the agent to run: + +```bash +printf 'PWD=%s\nHOME=%s\n' "$PWD" "$HOME" +find "$HOME" -mindepth 1 -maxdepth 1 -printf '%f\n' | sort +``` + +A default execution image should report `/workspace` as `PWD` and a container-local home directory such as `/home/openhands`. It must not display the Agent Server host's home-directory contents. + +On the host, inspect the active execution container: + +```bash +docker ps --filter name=openhands-execution- +docker inspect --format '{{json .Mounts}}' +``` + +For an ephemeral configuration, the mounts output should be `[]`. + +## Configuration Reference + +| Variable | Default | Purpose | +|----------|---------|---------| +| `OH_EXECUTION_RUNTIME` | `local` | Set to `docker` to enable one execution container per local conversation. | +| `OH_EXECUTION_IMAGE` | `ghcr.io/openhands/agent-server:latest-python` | Agent Server image used for execution containers. | +| `OH_EXECUTION_PLATFORM` | `linux/amd64` | Docker platform for execution containers. | +| `OH_EXECUTION_VOLUMES` | `[]` | Optional JSON array of Docker volume specifications. | + +## Related Guides + +- [Use Docker with Agent Canvas](/openhands/usage/agent-canvas/backend-setup/docker) — run the entire Canvas distribution and backend in one container +- [Agent Canvas Architecture](/openhands/usage/agent-canvas/architecture) +- [Docker Sandbox](/sdk/guides/agent-server/docker-sandbox) — run the entire conversation through a remote Agent Server container ### Kubernetes (Helm) Source: https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/kubernetes.md @@ -29847,7 +30550,7 @@ Switch between them from the backend selector depending on what you're working o ### Modal Backend Source: https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/modal.md -Deploy [Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server) on [Modal](https://modal.com) as a remote backend for Agent Canvas. Canvas runs locally on your machine while Agent Server runs on Modal and executes code inside the container—the same execution model as the backend started by `npx @openhands/agent-canvas`. +Deploy [OpenHands](https://github.com/OpenHands/OpenHands) on [Modal](https://modal.com) as a remote backend for Agent Canvas. Canvas runs locally on your machine while the Agent Canvas Backend runs on Modal and executes code inside the container—the same execution model as the backend started by `npx @openhands/agent-canvas`. The agent server runs with full access to the container's filesystem, environment, and network. Anyone with the API key can execute arbitrary code on your Modal container. Keep the API key secret and rotate it if it's ever exposed. @@ -30204,10 +30907,10 @@ Agent Canvas does not distinguish a remote backend by where it runs. It connects A remote backend must provide: - An accessible Agent Server URL. -- An API key when the backend requires authentication. +- An API key. - A workspace or sandbox where Agent Server can execute tools. -To use scheduled or event-driven automations, the backend must also provide Automation Server. +To use scheduled or event-driven automations, the backend must also provide an Automation Server. ## Connect To A Remote Backend @@ -30582,28 +31285,220 @@ Before exposing Agent Canvas beyond an SSH tunnel: ### Backends Source: https://docs.openhands.dev/openhands/usage/agent-canvas/backends.md -A **backend** provides Agent Server and, when automations are enabled, Automation Server. Agent Server runs conversations and tools in a workspace: the folder, mounted project directory, container, or cloud sandbox where the agent reads and writes files. Automation Server manages schedules, events, and run lifecycle. Agent Canvas connects to these services and displays the state of whichever backend is selected. +A **backend** provides [Agent Server](/sdk/guides/agent-server/overview#what-is-a-remote-agent-server) and, when automations are enabled, Automation Server. Agent Server runs conversations and tools in a workspace: the folder, mounted project directory, container, or cloud sandbox where the agent reads and writes files. Automation Server manages schedules, events, and run lifecycle. Agent Canvas connects to these services and displays the state of whichever backend is selected. ## Connecting to a Backend Any Agent Canvas frontend can connect to any Agent Canvas backend. Use the backend switcher in the UI to open **Manage Backends**, where you can add, edit, or remove entries. Each entry stores a display name, host URL, and an API key for authentication. +![Agent Canvas Add Backend dialog on the Agent Server tab with synthetic display name, host URL, and masked API key fields.](/openhands/static/img/agent-canvas-add-backend-agent-server.png) + Settings, LLM configuration, MCP servers, and automations are all scoped to the active backend — switching backends switches all of these. +"Remote" describes how Canvas connects to a backend, not where that backend runs. A remote backend can be a separate process on the same machine, a self-hosted deployment on a VM or container platform, or a managed Cloud or Enterprise service. + ## Recommended Setups | Setup | When to use | How | |-------|-------------|-----| | **Default local** | Quick local work on your machine | Run `agent-canvas`—a local backend is created automatically. | -| **Remote Agent Server** | An Agent Server on another machine or in a separate local container | Add its host URL and API key in `Manage Backends`. See [Remote Backend](/openhands/usage/agent-canvas/backend-setup/remote). | -| **Self-hosted VM** | Always-on server, more powerful hardware, team-shared access, or a full self-hosted Canvas | Run `agent-canvas --backend-only --public` for backend-only mode, or `agent-canvas --public` for the full UI and backend. See [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). | +| **Self-hosted backend** | A separate local process or container, an always-on VM, more powerful hardware, or team-shared access | Deploy the backend services, then add their host URL and API key in `Manage Backends`. See [Remote Backend](/openhands/usage/agent-canvas/backend-setup/remote) and [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). | | **Cloud or Enterprise** | Managed backend and sandbox infrastructure | Connect from `Manage Backends`. See [Cloud Backend](/openhands/usage/agent-canvas/backend-setup/cloud). | +### Apps (Beta) +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/canvas-extensions.md + +Apps let you add custom pages to Agent Canvas without changing the Agent Canvas source code. An app can provide an integrated dashboard, project tool, or other browser interface that connects to the active Agent Server. + + + Apps are a beta feature. The name and app API may change as the feature develops. + + +## What Apps Add + +The initial beta supports **custom pages**. When you enable an app, its pages appear in the Agent Canvas sidebar and open inside the application. + +An app 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 app and active backend + +The current beta does not support conversation tabs, arbitrary interface slots, themes, visualizer replacement, or direct Agent Server WebSocket connections. + +Apps 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 + +Apps 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 apps, files, versions, and enabled states. Switching backends replaces the apps shown in Agent Canvas. + +If `Customize > Apps` 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 apps. + +## Install an App + +Open `Customize > Apps`, then select `Add app`. + + + + 1. Enter the Git source, such as `github:owner/repository`. + 2. Optionally enter a branch, tag, or commit in `Ref`. + 3. If the app is not at the repository root, enter its directory in `Repo path`. + 4. Select `Add app`. + + + 1. Enter the absolute path to the app directory. + 2. Select `Add app`. + + 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 app operation installs one app package. If a repository contains several apps, add each manifest directory separately with its own `Repo path`. + +New apps are installed **disabled**. Review the source, resolved revision, manifest details, and contributed pages before enabling one. + +## Enable and Manage Apps + +To run an installed app: + +1. Open `Customize > Apps`. +2. Find the installed app 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 app without restarting Agent Canvas. Its navigation items and mounted pages are removed immediately. Re-enable it to load the app again, or uninstall it to remove the installation from the active backend. + +### Trust Model + +Enabling an app runs its JavaScript in the same browser context as Agent Canvas. The beta does not isolate apps in an iframe or worker and does not enforce fine-grained permissions. + +Only enable apps whose code and resolved revision you trust. An enabled app has the browser authority available to Agent Canvas and can use an authenticated helper to call the active Agent Server. + +## Build an App + +An app is a directory containing: + +- `canvas-extension.json` at the app 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 app names and page IDs. Page paths must start with `/`, and every page ID and path must be unique within the app. + +The `entrypoint` must stay inside the app 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 app 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 app: + +```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 app repeatedly when you enable or disable it, update it, reconnect, or switch backends. App pages should: + +- Render only inside the supplied page container +- Scope styles to an app-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 API specification](https://github.com/OpenHands/OpenHands/blob/main/specs/canvas-extensions.md) +- [Minimal app fixture](https://github.com/OpenHands/OpenHands/tree/main/src/fixtures/canvas-extensions/demo-page) +- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) + ### Conversations Source: https://docs.openhands.dev/openhands/usage/agent-canvas/conversations.md A conversation is a single agent session on the active backend. It has its own message history, tool calls, file changes, selected agent profile, and conversation-specific plugins. +## Child Conversations + +When an agent uses `launch_child_conversation`, Agent Canvas can launch a child conversation on a local or Cloud target. Local children can use either an isolated worktree or the parent's shared workspace. Cloud children use the repository and branch selected for the launch. + +The child remains linked to its parent, and its result is returned to the parent conversation. Agent Canvas validates the launch inputs before creating the child conversation. + +## Conversation List Controls + +Use the conversation list controls to manage automation runs and visible tags: + +- Choose `All`, `Hide`, or `Only` to include, exclude, or show only automation-run conversations. You can further select individual automation names, including unnamed automations. +- Pinned conversations remain visible when automation-run filtering would otherwise hide them. +- Enable the `Tags` preference to show conversation tag chips. Tags are off by default; when there are more tags than fit, Agent Canvas shows a `+N` chip with the remaining count. + +Agent Canvas omits reserved tags and raw automation IDs from the chips. LLM metadata is also hidden by default. + ## Follow Agent Activity While an agent is running, the composer shows a live activity chip for its current unresolved action, such as reading a file or running a command. If no action-specific label is available, it shows `Thinking`. The chip disappears when the agent pauses or completes its work. @@ -30612,6 +31507,45 @@ While an agent is running, the composer shows a live activity chip for its curre If a message fails to send, select `Retry` to send it again or `Dismiss` to remove the failed message bubble. Dismissing a message does not restore its text to the composer. +## Inline Markdown Artifact Previews + +When an agent creates a Markdown file, Agent Canvas renders it inline as a height-limited rich preview with an internal scrollbar instead of showing only the raw file content. Select `View` to open the full file in the Files drawer. + +## Conversation Overview Panel + +The conversation overview panel displays project context for the active conversation, including workspace information, git state, and loaded resources such as skills, MCP servers, and automations. + +Toggle the overview using the info control in the conversation header. The panel peeks beside the chat area and closes when you open the Files drawer. + +### Unified Commits Drawer + +From the overview panel, open the **Commits** drawer to see a unified view of git activity: + +- The commit list shows recent commits alongside any uncommitted changes +- A header git-actions control lets you send commit, pull, push, and pull-request prompts to the agent + +The Commits tab combines the commit history with uncommitted changes in a single view, so you no longer need to switch between separate Diff and Commits surfaces. + +### Files View + +The **Files** tab is a focused file browser with open-file tabs and close controls. The file tree is resizable and persists its state across refreshes. + +Above the file tree, the active workspace path is displayed with a copy button. Hover the truncated path to see the full value in a tooltip, then click to copy it. + + + The workspace path row is hidden when the conversation has no working directory. + + +## Context Window Usage and Manual Compaction + +Agent Canvas shows a context-window meter in the composer that visualizes how much of the model's available context is in use. The meter fills as the conversation grows. + +Click the meter to open the usage preview, then click "Usage" to see the full usage panel which shows token usage and provider balance details. You can manually compact the conversation to reduce context by selecting "Compact context" in the usage preview or usage panel. + + + The meter only appears for models that report a context window size. Models that do not report one will not show a meter. + + ## Branch From a Message Use `Branch from here` on a message when you want to explore a different path without changing the original conversation. @@ -30726,6 +31660,29 @@ The export is generated locally in your browser from the events Agent Canvas alr For very large conversations, Agent Canvas loads the full event history before generating the file. This may take a moment. On cloud backends, the export uses the events the app currently has loaded. +## Archive a Conversation + +Archiving a conversation hides it from the sidebar list without deleting it. The conversation's full history stays on the backend, and you can unarchive it at any time. + +**To archive a conversation:** + +1. Open the conversation card menu in the sidebar. +2. Select `Archive`. +3. Confirm in the dialog that appears. + +The conversation disappears from the default sidebar list. An archived conversation shows an `Archived` chip when revealed. + +**To view or restore archived conversations:** + +1. Open the panel filter menu in the sidebar. +2. Enable `Show archived`. +3. Archived conversations reappear with an `Archived` chip. +4. Open an archived conversation's menu and select `Unarchive` to restore it to the default list. + + + Archive state is stored per backend in your browser's local storage. It does not sync across browsers or machines. The `Delete all` action still deletes archived conversations, including hidden ones. Archiving is non-destructive, but deleting is permanent. + + ## Related Guides - [Fork a Conversation](/sdk/guides/convo-fork) @@ -30877,11 +31834,12 @@ Agent Canvas separates **Customize** from **Settings**. Open the top-level `Customize` area to manage: -- [Skills](/overview/skills) - [MCP Servers](/openhands/usage/settings/mcp-settings) +- [Skills](/overview/skills) - [Plugins](/openhands/usage/agent-canvas/plugins) +- [Apps (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. Apps 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`. @@ -30915,15 +31873,16 @@ The `Settings` area currently includes the following sections: | Section | Purpose | |---------|---------| | `Agent` | Agent Profile library and agent-specific capabilities | -| `LLM` | Provider, model, API key, and profile configuration | +| `LLM` | Provider, model, API key, profile configuration, and provider connections | | `Condenser` | Context compression and summarization behavior | | `Verification` | Approval, critic evaluation, and verification-related behavior | | `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. -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. +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 main settings nav also shows the installed version of Agent Canvas with a manual **Check for updates** button. When an update is available click on the tile to view details and update information. Use `Settings > Agent` to choose the active Agent Profile for new conversations. OpenHands profiles reference LLM profiles from `Settings > LLM`; ACP profiles use the external agent's own model configuration. @@ -31032,6 +31991,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 @@ -31051,12 +32012,152 @@ Other available templates include: 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 + +After completing the setup wizard, a **Getting Started** checklist appears in the sidebar. It guides you through the core first actions: + +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` + +Each item links directly to the relevant page. The checklist tracks your progress and minimizes to stay out of the way. When all items are complete, the checklist auto-hides. + + + Toggle the checklist from `Settings > Application` using the **Show getting started checklist** switch. The setting persists across sessions. + + +## Customize your Agent Canvas + +When you are ready to go beyond the default setup, choose the mechanism that fits the task: + +- Add repository-wide guidance with [`AGENTS.md`](/overview/skills/repo) for each Workspace. +- Add reusable task instructions with [Skills](/overview/skills). +- Connect external tools through [MCP](/openhands/usage/settings/mcp-settings). +- Add packaged capabilities with [Plugins](/openhands/usage/agent-canvas/plugins). +- Automate repeated work with [Automations](/openhands/usage/agent-canvas/managing-automations). + ## After Your First Session Keep the terminal or Docker container that runs Agent Canvas active while you use the browser. When you are done, [stop Agent Canvas](/openhands/usage/agent-canvas/setup#stop-agent-canvas). Start it again with the same command when you return. For routine maintenance, see [update and uninstall](/openhands/usage/agent-canvas/setup#update-agent-canvas). If the UI, backend, or model does not work as expected, start with [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting). +### Sync Automations with Git +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/git-sync.md + +Git Sync keeps the automations on an Agent Canvas backend synchronized with a Git repository. It gives you version history, an off-host backup, and a reviewable workflow for changing automations through pull requests. + + + Automation definitions can contain prompts, repository names, scripts, and other sensitive configuration. Use a private repository unless you are certain every synchronized file is safe to publish. + + +## How Git Sync Works + +Each sync cycle pulls the configured branch, imports changes from Git into the Automation Server, exports local automation changes, and pushes a commit when the synchronized files changed. + +By default, each automation is stored in its own directory under the configured path: + +```text +automations/ +└── daily-code-review/ + ├── automation.yaml + └── tarball/ + └── ... +``` + +The `automation.yaml` file stores the automation configuration. Files from an uploaded automation bundle are expanded under `tarball/` so Git can show meaningful diffs. + + + Git Sync is bidirectional. A change made in Agent Canvas is exported to Git, while a change merged into the synchronized branch is imported into Agent Canvas during the next cycle. If the same automation has pending local changes, the local version takes precedence for that cycle. + + +## Requirements + +Before configuring Git Sync, make sure you have: + +- A healthy Agent Canvas backend with a version of Automation Server that supports Git Sync +- Permission to manage automations on that backend +- A Git repository and branch dedicated to the synchronized automation files +- An HTTPS access token with read and write access when the repository is private + +Git Sync is not available for cloud backends. If the page reports that the backend does not support Git Sync, [update Agent Canvas](/openhands/usage/agent-canvas/setup#update-agent-canvas) and restart it. + +## Configure Git Sync + +1. Open the `Automate` view in Agent Canvas. +2. Select `Git Sync` near the top of the automation list. +3. Configure the repository: + - `Repository URL`: The HTTPS clone URL, such as `https://github.com/example/automation-backup.git`. + - `Branch`: The branch Git Sync pulls from and pushes to. The default is `main`. Git Sync creates the branch during the first cycle if it does not exist. + - `Path`: The repository-relative directory that holds automation files. The default is `automations`. + - `Access token`: Required for private repositories. The token needs permission to read and push repository contents. +4. Set `Sync every (seconds)`: + - Enter `0` to sync only when you select `Sync now`. + - Enter a positive number to run automatic sync cycles at that interval. +5. Optionally set the commit author name and email. Leave these fields blank to use the backend defaults. +6. Optionally enter an encryption key. See [Encrypt Synchronized Files](#encrypt-synchronized-files) before enabling this option. +7. Turn on `Enable Git Sync`. +8. Select `Save and sync now`. + +Before saving a changed repository URL, branch, or token, Agent Canvas checks whether it can reach the repository. This check does not verify push permission, so the first sync can still fail if the token is read-only. If the check cannot reach the repository, correct the settings or select the save action again to store them anyway. + +After the cycle completes, the **Sync Status** section shows the latest commit, last sync time, pending local changes, and any error returned by Git. + +## Encrypt Synchronized Files + +An encryption key encrypts each automation file before it is committed. The repository then contains ciphertext instead of readable YAML and script content. + + + Store the encryption key in a password manager or another secure location. Agent Canvas cannot read or restore encrypted automation files without the same key. + + +Encryption protects the contents stored in Git, but it also prevents normal code review and meaningful diffs. Use it when repository-level access controls are not sufficient for the sensitivity of your automation definitions. + +The access token and encryption key entered in Agent Canvas are encrypted before the Automation Server stores them. Leaving either secret field blank keeps its current value. Use the corresponding clear option when you intend to remove a stored secret. + +## Edit Automations Through Git + +Use a pull request when you want to review automation changes before Agent Canvas imports them: + +1. Create a branch from the synchronized branch. +2. Edit the automation's `automation.yaml` or files under `tarball/`. +3. Open and review a pull request. +4. Merge the pull request into the synchronized branch. +5. Wait for the next automatic cycle or select `Sync now`. +6. Open the automation in Agent Canvas and confirm the imported configuration before running it. + +Git Sync validates imported automation fields. It skips an invalid automation directory and reports the problem in Automation Server logs rather than applying a partial configuration. + + + If file encryption is enabled, edit automations in Agent Canvas instead. Encrypted repository files are not directly editable or reviewable. + + +## Pause or Run Sync Manually + +Turn off `Enable Git Sync` and save to pause synchronization without deleting the repository configuration. Turn it on again to resume. + +Select `Sync now` to start a cycle immediately. The request schedules the cycle in the background, and the activity row follows it until it succeeds or fails. If another cycle is already running, Agent Canvas follows that cycle instead of starting a duplicate. + +## Troubleshooting + +| Problem | What to Check | +|---------|---------------| +| Git Sync is not available | Confirm the active backend is local, healthy, and running a current Automation Server version. | +| Repository check fails | Confirm the HTTPS URL, branch name, network access, and token. Select save again only if you intentionally want to keep settings that the check cannot verify. | +| Repository check passes but push fails | Give the access token write permission for repository contents and confirm branch protection permits the configured workflow. | +| Sync reports a non-fast-forward or divergence error | Update the synchronized branch through reviewed pull requests and avoid another process writing directly to it while Agent Canvas has an unpushed commit. | +| Encrypted files cannot be imported | Restore the exact encryption key used to write them. A different or missing key cannot decrypt the repository contents. | +| Changes do not sync automatically | Confirm Git Sync is enabled and `Sync every (seconds)` is greater than `0`, or use `Sync now`. | + +## Related Guides + +- [Manage Automations](/openhands/usage/agent-canvas/managing-automations) +- [Install Agent Canvas](/openhands/usage/agent-canvas/setup) +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) + ### Manage LLM Profiles Source: https://docs.openhands.dev/openhands/usage/agent-canvas/llm-profiles.md @@ -31068,6 +32169,8 @@ LLM profiles can also generate conversation titles. In `Settings > Application > Open `Settings > LLM` to add a reusable LLM profile. Use the **Basic** tab for a provider and model available in the dropdowns. Use the **Advanced** tab when you need to enter a model name and base URL directly. Use the **All** tab to view and customize the full set of model configuration fields. +If you are deciding between a provider key, local endpoint, LiteLLM proxy, OpenRouter, or ACP agent, start with [Configure a Model](/openhands/usage/agent-canvas/model-configuration). + ACP agents such as Claude Code, Codex, and Gemini CLI manage their own model access. See [ACP Agents](/openhands/usage/agent-canvas/acp-agents) instead. @@ -31076,14 +32179,14 @@ ACP agents such as Claude Code, Codex, and Gemini CLI manage their own model acc | I have | Profile tab | Configure | |---|---|---| -| An API key from Anthropic, OpenAI, Google, or another provider | **Basic** | Select the provider and model, then add its API key. | -| An OpenHands LLM API key | **Basic** | Select `OpenHands`, choose a model, and add your OpenHands LLM API key. | -| A local OpenAI-compatible server | **Advanced** | Enter the provider, exact model ID, base URL, and any required API key. | -| A LiteLLM proxy | **Advanced** | Use the `litellm_proxy/` model prefix, proxy base URL, and proxy API key. | +| An API key from Anthropic, OpenAI, Google, or another provider | **Basic** | Select the provider and model, then add its API key or reuse a Provider Connection. | +| An OpenHands LLM API key | **Basic** | Select `OpenHands`, choose a model, then add the key or reuse a Provider Connection. | +| A local OpenAI-compatible server | **Advanced** | Enter the provider and exact model ID, then add its base URL/key or reuse a Provider Connection. | +| A LiteLLM proxy | **Advanced** | Use the `litellm_proxy/` model prefix, then add its proxy URL/key or reuse a Provider Connection. | ### Direct Provider -In the **Basic** tab, select your provider and model, add the API key issued by that provider, and save the profile. Use a new conversation to test the change; an existing conversation continues with the agent and model it started with. +In the **Basic** tab, select your provider and model. Select a **Provider Connection** to reuse its API key, or add an API key directly when it belongs only to this profile. Save the profile, then use a new conversation to test the change; an existing conversation continues with the agent and model it started with. For provider and model recommendations, see [LLM Configuration](/openhands/usage/llms/llms). @@ -31095,8 +32198,20 @@ 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 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 **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). +### Pre-Save Validation + +When you save an LLM profile, the configuration is validated against the backend before it is persisted. If validation fails — for example, because the API key is rejected or the model is unavailable — the save is blocked and the backend error is shown. The save button displays a validating state while the check runs. + +Older backends that do not support validation (they return a `404` for the validation endpoint) skip this check and save normally. + ### 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. @@ -31117,6 +32232,32 @@ In the **Advanced** tab, use the model name format `litellm_proxy/`, See [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy) for the complete configuration. +## Provider Connections + + + Provider Connections are available on **local agent-server backends only**. The panel is hidden when using an OpenHands Cloud backend. + + +When you want multiple LLM profiles to share the same provider credentials, use **Provider Connections** to store a provider, API key, and optional base URL once and reference it across profiles. This avoids pasting the same key into every profile and lets you rotate credentials in one place. Linked profiles keep their own model selection while using the shared connection for credentials. + +### Create a Provider Connection + +1. Open `Settings > LLM`. +2. In the **Provider Connections** panel, add a new connection. +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 + +When you add or edit an LLM profile, choose a saved connection in the **Provider Connection** selector. Select **None** to use credentials specific to that profile instead. When a profile is linked, its inline API key and base URL fields are hidden — the profile uses the connection's credentials instead. + +Linked profiles are grouped under their Provider Connection name in the profile list for readability. To use another model with the same API key, add another LLM profile, select the same connection, choose that model, and save. + +### Update or Delete a Connection + +Edit a Provider Connection to rename it, rotate its API key, or change its base URL. The update applies to every linked profile. Before deleting a connection, re-link or change every profile that uses it; Agent Canvas prevents deleting a connection while profiles still reference it. + ## Working with LLM Profiles LLM profiles are useful when you want different model setups for different tasks, such as: @@ -31131,6 +32272,8 @@ LLM profiles are separate from [Agent Profiles](/openhands/usage/agent-canvas/ag The available profiles list shows each profile's name, configured model, and whether it is active. Use a profile's menu to edit or rename it, set it as the active profile for new conversations, or delete it when you no longer need it. +![Agent Canvas LLM settings showing two synthetic saved profiles, one marked as the default, with its profile actions menu open.](/openhands/static/img/agent-canvas-llm-profiles-manager.png) + ## Switching Profiles in a Conversation You can switch profiles from the profile selector in the chat input or with the `/model` command: @@ -31183,7 +32326,7 @@ The **Automate** view in Agent Canvas is the in-app control center for your auto ## 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. +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: @@ -31196,6 +32339,16 @@ 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, 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. @@ -31256,12 +32409,16 @@ You can import an automation from a JSON file previously exported by Agent Canva 2. Click **Import automation** at the top of the list. 3. Pick the `.json` file to import. 4. Review the preview — it shows the automation's name, trigger type, and prompt. + +![Agent Canvas import automation dialog previewing the Weekly Documentation Review name, schedule, and prompt before import](/openhands/static/img/agent-canvas-automation-import-preview.png) + 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 +- [Sync automations with Git](/openhands/usage/agent-canvas/git-sync) - [Creating automations](/openhands/usage/automations/creating-automations) - [Managing automations (CLI-style)](/openhands/usage/automations/managing-automations) - [Pre-built automations](/openhands/usage/agent-canvas/prebuilt-automations) @@ -31318,6 +32475,105 @@ Open the ngrok forwarding URL in your phone or tablet browser. ngrok also supports OAuth, IP allowlists, and other access controls for additional protection. +### Configure a Model +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/model-configuration.md + +Use this guide to choose a model configuration path in Agent Canvas. Start with the credentials or endpoint you have, then save the profile and test it in a new conversation. + + +ACP agents such as Claude Code, Codex, and Gemini CLI manage their own model access. Use [ACP Agents](/openhands/usage/agent-canvas/acp-agents) instead of creating an LLM profile for those agents. + + +## Choose a Configuration Path + +| I have | Use | Configure in | +|---|---|---| +| An API key from a model provider | A direct provider profile | `Settings > LLM` → `Basic` | +| An OpenHands LLM API key | An OpenHands provider profile | `Settings > LLM` → `Basic` | +| A local OpenAI-compatible server | A local endpoint profile | `Settings > LLM` → `Advanced` | +| A LiteLLM proxy | A proxy profile | `Settings > LLM` → `Advanced` | +| A signed-in Claude Code, Codex, or Gemini CLI subscription | An ACP agent | `Settings > Agent` | + +## Provider Connection for Reusable API Credentials + +Create a **Provider Connection** when you expect to use the same provider API key for more than one model or LLM profile. A connection stores the provider, API key, and optional base URL once; each linked profile supplies its own model configuration and uses the connection's credentials. + +1. Open `Settings > LLM`. +2. In **Provider Connections**, select **Add provider connection**. +3. Enter a recognizable name, such as `Personal OpenHands API` or `Team OpenAI`. +4. Choose the provider from the searchable provider list. +5. Enter the API key and, if needed, the provider base URL. +6. Save the connection. +7. Add or edit an LLM profile, select the connection in **Provider Connection**, then select the model and save the profile. + +When a profile uses a Provider Connection, its API key and base URL come from the connection rather than the profile. Reuse that connection for additional models from the same provider. Update the connection once to rotate its key or change its base URL for every linked profile. + + +Provider Connections are available on local agent-server backends. The panel is hidden when using an OpenHands Cloud backend. + + +## Direct Provider or OpenHands Profile + +Use the `Basic` tab when you have an API key from Anthropic, OpenAI, Google, OpenHands, or another provider in the selector. + +1. If you will reuse the key, create or choose a [Provider Connection](#provider-connection-for-reusable-api-credentials). +2. Select the provider and model. +3. Select the Provider Connection, or enter the API key directly for a profile-specific credential. +4. Save the profile. +5. Start a new conversation and send a short message to confirm the model responds. + +For model recommendations and provider references, see [LLM Configuration](/openhands/usage/llms/llms). For the OpenHands provider, see [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms). + +## Local OpenAI-Compatible Server + +Use the `Advanced` tab for LM Studio, Ollama, vLLM, SGLang, or another server that exposes an OpenAI-compatible API. + +1. Find the exact model ID served by your server, usually from its `GET /v1/models` endpoint. +2. Enter `openai/` as the model. +3. If the server needs an API key or a reusable base URL, create a [Provider Connection](#provider-connection-for-reusable-api-credentials) with those values and select it for the profile. Otherwise, enter them directly in the profile. +4. Make sure the base URL is reachable from the **backend**. +5. Save the profile and start a new conversation to verify it. + +If Agent Canvas runs in Docker while the model server runs on the host, `127.0.0.1` points to the container, not the host. Use the host address appropriate for your platform, such as `http://host.docker.internal:/v1` where supported. + +See [Run Local LLMs with OpenHands](/openhands/usage/llms/local-llms) for server-specific examples. + +## LiteLLM Proxy + +Use the `Advanced` tab when you use a LiteLLM proxy. + +1. Enter `litellm_proxy/` as the model. +2. Create or select a [Provider Connection](#provider-connection-for-reusable-api-credentials) for the proxy URL and API key. You can instead enter those values directly when they are specific to one profile. +3. Make sure `` exactly matches a model configured on the proxy. +4. Save the profile and start a new conversation to verify it. + +See [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy) for the complete proxy configuration. + +## OpenRouter + +Use OpenRouter when you have an OpenRouter API key and want to access a model through its catalog. Create an `OpenRouter` Provider Connection to reuse the key, then in the `Basic` tab select `OpenRouter`, choose a model, select the connection, and save the profile. Use the `Advanced` tab only when you need to enter a model ID that is not available in the selector. + +See [OpenRouter](/openhands/usage/llms/openrouter) for model-ID and recovery guidance. + +## Fix a Failed Configuration + +| Symptom | Check first | Next step | +|---|---|---| +| Provider is not recognized | The profile path and provider/model prefix | Choose the matching path above. | +| Model ID or format error | The exact model ID from the provider or proxy inventory | Update the model ID or prefix. | +| Local endpoint cannot be reached | The base URL from the backend | Check host, port, bind address, and container networking. | +| Authentication or permission error | Key type and provider account access | Re-enter the key and check the provider requirements. | +| The model cannot complete agent tasks | Context length and tool-use support | Use a more capable model or supported runtime. | + +For additional error-specific guidance, see [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting#model-or-api-key-errors). + +## Next Steps + +- [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) +- [Run Local LLMs with OpenHands](/openhands/usage/llms/local-llms) +- [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy) +- [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting) + ### Agent Canvas Overview Source: https://docs.openhands.dev/openhands/usage/agent-canvas/overview.md @@ -31343,16 +32599,27 @@ You can also test a preview build of the native desktop app. [Try the desktop pr Agent Canvas is the browser client. It connects to backend services that own execution and persistent state: -| Component | Responsibility | -|-----------|----------------| -| **Agent Canvas** | Displays conversations, files, terminals, settings, backends, and automations. | -| **Agent Server** | Runs conversations, agents, tools, and workspace operations. | -| **Automation Server** | Manages schedules, event triggers, dispatch, and run history. | -| **Workspace or sandbox** | Defines which files, processes, credentials, and networks the agent can access. | +| Concept | What It Means | Why It Matters | +|-------|---------------|----------------| +| **Browser UI** | The web interface you open in your browser. | This is where you chat, inspect files, manage settings, and configure automations. | +| **Backend** | The agent server that runs conversations, tools, settings, secrets, and automations. | This determines where the agent runs and what machine or sandbox it can access. | +| **Workspace** | The folder, repository, container mount, or cloud sandbox the agent works in. | This determines which files the agent can read and write. | +| **Agent and model** | The OpenHands agent or an ACP agent, plus the model credentials it uses. | This determines which LLM or provider receives conversation context and powers the agent. | + +```mermaid +flowchart LR + browser["Browser UI"] --> backend["Selected backend"] + backend --> conversation["Conversation and agent"] + conversation --> model["Model access"] + conversation --> workspace["Workspace and tools"] - - Agent Canvas does not execute tools or provide sandbox isolation. Agent Server or an ACP process executes tools, and the selected workspace or sandbox provides the execution boundary. - + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + class browser primary + class backend,conversation secondary + class model,workspace tertiary +``` The `agent-canvas` launcher can package the client and backend services into one local stack. You can also run the client separately and connect it to services on a VM, in Docker or Kubernetes, or through OpenHands Cloud or OpenHands Enterprise. @@ -31392,7 +32659,19 @@ Agent Canvas supports several model access patterns: - **ACP agent subscription login** — use a signed-in provider, such as Claude Code, Codex, or Gemini, when the backend runs on the same machine as that login. - **Local or OpenAI-compatible provider** — connect providers such as Ollama, LM Studio, LiteLLM, or a compatible gateway through model settings. -See [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) and [ACP Agents](/openhands/usage/agent-canvas/acp-agents) for details. +See [Configure a Model](/openhands/usage/agent-canvas/model-configuration), [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles), and [ACP Agents](/openhands/usage/agent-canvas/acp-agents) for details. + +## Customize Your Agent + +After the first conversation, choose the extension point that matches your need: + +| If you want to... | Start here | +|---|---| +| Add always-on repository guidance | [Repository Context and `AGENTS.md`](/overview/skills/repo) | +| Add reusable task-specific instructions | [Skills Overview](/overview/skills) | +| Connect external tools or services | [MCP Settings](/openhands/usage/settings/mcp-settings) | +| Extend the agent with packaged capabilities | [Plugins](/openhands/usage/agent-canvas/plugins) | +| Run work on a schedule or in response to events | [Automations](/openhands/usage/agent-canvas/managing-automations) | ## How It Fits With Other OpenHands Products @@ -31532,7 +32811,7 @@ Agent Canvas ships with a set of pre-built automations for the most common agent --- -Backends created by the `agent-canvas` launcher include Automation Server, so they can run agents on a schedule or in response to external events. Other backends must provide a compatible automation service for these features. +Backends created by the `agent-canvas` launcher include Automation Server, so they can run agents on a schedule or in response to external events. ## What You Can Do @@ -31555,8 +32834,16 @@ In practice, new automation setup starts in one of two ways: For recommended automations that support a direct form setup, Agent Canvas checks the active backend's capabilities and any prerequisites, then guides you through the required input fields, a review step, and creation. If direct form setup is unavailable, it offers a conversation-assisted setup instead. Review the proposed configuration before creating an automation. +Some catalog entries ship a **script bundle** — a packaged set of files that install as a deterministic automation — rather than a prompt-based preset. Script-bundle entries run their own logic for tasks like polling, deduplication, and fixed API calls, using the agent only for the parts that genuinely require judgment. When a catalog entry supports a bundle install, the setup form handles packaging and upload automatically; you just fill in the required fields. + +Catalog entries that accept repositories can also collect multiple repositories in a single field, so one automation can monitor several repos at once. + For a detailed walkthrough, see [Creating Automations](/openhands/usage/automations/creating-automations). + + Some recommended automations depend on integrations that cannot be auto-installed as MCP servers on this backend (for example, Jira's HTTP/OpenAPI-only integration). These appear on the recommendation card with a `Needs external setup` label. The `MCPs to connect` count only covers integrations the install flow can connect automatically. You must configure externally-hosted integrations yourself before the automation can use them. + + Automations run against the active backend. Use [Manage Backends](/openhands/usage/agent-canvas/backends) to see and switch which backend your automations run on. ## Edit an Automation's LLM Profile @@ -31916,13 +33203,252 @@ After the automation is created: - [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations) - [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) +### Agent Canvas 1.10.0 +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/release-notes/v1.10.0.md + +# Agent Canvas 1.10.0 + +Released August 5, 2026. + +[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.10.0). + +## Highlights + +- **Canvas default model set to GLM 5.2** — New conversations now use GLM 5.2 as the default model, providing a better out-of-the-box experience without requiring manual model selection. +- **Activity Log export** — Users can export the full Activity Log for a conversation, making it easier to share agent trajectories and audit work outside of Canvas. +- **Featured Automations dashboard** — A new landing dashboard surfaces featured automations, helping users discover and set up prebuilt workflows directly from the home screen. +- **Faceted skills filter** — The skills page now includes a faceted filter rail, letting users quickly narrow down skills by category, source, or status. +- **Manifest-driven automation sub-pages** — Automations can now define their own sub-pages via a manifest, enabling richer configuration UIs without custom frontend code. + +## Improvements and fixes + +- Automation timeout cap is now derived from the deployment configuration, preventing runs from being silently capped by stale defaults. +- Sidebar conversation links are pinned to the correct backend identity, fixing broken navigation when multiple backends are connected. +- Local proxy targets now use IPv4 loopback addresses, resolving connection failures on systems where IPv6 loopback is not configured. +- Resolved all npm audit vulnerabilities reported in the frontend dependency tree. +- MCP server credentials are preserved during Canvas settings mutations, preventing credential loss when toggling or editing other settings. + +## Full changelog + +- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.10.0) +- [Compare v1.9.0 to v1.10.0](https://github.com/OpenHands/OpenHands/compare/v1.9.0...v1.10.0) + +### Agent Canvas 1.11.0 +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/release-notes/v1.11.0.md + +# Agent Canvas 1.11.0 + +Released August 7, 2026. + +[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.11.0). + +## Highlights + +- **Per-run LLM cost in Activity Log** — Each Activity Log entry and CSV export now includes the LLM cost for that run, giving users visibility into spending at the conversation level. +- **Typed agent action for child conversations** — A new typed action lets agents programmatically launch local or Cloud child conversations, enabling structured delegation workflows. +- **Automation tag filter and recognition** — Automations can now be tagged, and the UI supports filtering by tags so users can organize and find automations faster. +- **Conversation tag chips** — Conversations display tag chips with overflow and hovercard labels, making it easier to identify and group conversations by category. +- **Customize navigation reordered** — The Customize page navigation has been reorganized for a more logical flow between settings sections. +- **Version update UI polished** — The Agent Canvas version update experience has been refined with clearer status indicators and smoother transitions. +- **Automations pane always visible** — The home screen Automations pane now stays visible even when no automations are installed, guiding users toward setup. + +## Improvements and fixes + +- Multi-size application icons are now shipped for both Windows and macOS, eliminating blurry or missing icons in taskbars and docks. +- The desktop app has been renamed to "OpenHands Agent Canvas" for consistency across platforms. +- Runtime metrics now fetch the conversation directly instead of going through a removed cloud-proxy endpoint, fixing a broken metrics path. + +## Full changelog + +- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.11.0) +- [Compare v1.10.0 to v1.11.0](https://github.com/OpenHands/OpenHands/compare/v1.10.0...v1.11.0) + +### Agent Canvas 1.12.0 +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/release-notes/v1.12.0.md + +# Agent Canvas 1.12.0 + +Released August 7, 2026. + +[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.12.0). + +## Highlights + +- **Clarified free OpenHands model endpoints** — The free OpenHands model offerings now have clearer endpoint labeling, helping users understand which models are available at no cost and how to select them. + +## Full changelog + +- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.12.0) +- [Compare v1.11.0 to v1.12.0](https://github.com/OpenHands/OpenHands/compare/v1.11.0...v1.12.0) + +### Agent Canvas 1.13.0 +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/release-notes/v1.13.0.md + +# Agent Canvas 1.13.0 + +Released August 13, 2026. + +[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.13.0). + +## Highlights + +- **Context window usage meter and manual compaction** — A new context-window usage meter, usage drawer, and manual compaction control let users monitor and manage token consumption in real time, preventing unexpected context overflow. +- **Client-side conversation archive** — Users can archive conversations directly from the sidebar, keeping the active conversation list clean without permanently deleting work. +- **Inline markdown artifact previews** — Markdown artifacts rendered in chat now show inline previews, reducing the need to open a separate viewer for common output formats. +- **Ready-for-dev issue readiness gate** — A new readiness gate enforces type-specific criteria before issues are marked ready for development, improving workflow discipline. + +## Improvements and fixes + +- A postinstall message now explains how to start Agent Canvas after installation. +- Agent-server telemetry is now correctly configured when launched from Canvas. +- Overflow menus are now usable on touch devices, fixing a long-standing mobile interaction issue. +- The sidebar "Load more" button now correctly discovers folders rather than expanding folder contents prematurely. +- Chat input drag-resize is disabled when the input is not bottom-anchored, preventing unexpected layout shifts. +- Non-MCP-installable automation integrations are now surfaced instead of being silently dropped. +- A flaky `ProgressEvent` unhandled rejection in CI has been resolved. +- Launcher services are spawned without an implicit shell, improving reliability across environments. +- The Basic LLM provider list no longer truncates at 100 entries, ensuring all available providers are visible. +- The context meter ring track is now drawn from the foreground color instead of a border token, fixing visual inconsistency. +- Pending MSW callbacks are drained before jsdom teardown, eliminating a `ProgressEvent` `ReferenceError` in tests. + +## Full changelog + +- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.13.0) +- [Compare v1.12.0 to v1.13.0](https://github.com/OpenHands/OpenHands/compare/v1.12.0...v1.13.0) + +### Agent Canvas 1.14.0 +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/release-notes/v1.14.0.md + +# Agent Canvas 1.14.0 + +Released August 17, 2026. + +[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.14.0). + +## Highlights + +- **Structured error outcomes** — Agent errors are now presented as structured outcomes in the UI, making it easier to understand what went wrong and what action to take next. +- **LLM pre-flight validation** — A pre-flight check validates LLM configuration before saving a profile, preventing misconfigured profiles from being saved and causing failures at run time. +- **Git Sync page for automations** — A new Git Sync page lets automation authors manage how their automation repositories stay in sync, streamlining the automation development lifecycle. +- **Canvas default model set to Kimi K3** — New conversations now default to Kimi K3, which is tagged as free, lowering the barrier to entry for new users. + +## Improvements and fixes + +- Onboarding now preselects the OpenHands LLM provider after picking the OpenHands agent, reducing friction during first-time setup. +- Backend scope is preserved in conversation links, fixing broken navigation when switching between multiple backends. +- The `VITE_BACKEND_BASE_URL` is no longer baked at build time during `npm run dev`, allowing developers to point at different backends without rebuilding. +- Automation local responder URLs are now set from the browser origin, fixing webhook delivery in behind-proxy deployments. +- The full workspace file tree is now shown in the Files tab on cloud backends, restoring visibility into nested directories. + +## Full changelog + +- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.14.0) +- [Compare v1.13.0 to v1.14.0](https://github.com/OpenHands/OpenHands/compare/v1.13.0...v1.14.0) + +### Agent Canvas 1.15.0 +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/release-notes/v1.15.0.md + +# Agent Canvas 1.15.0 + +Released August 21, 2026. + +[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.15.0). + +## Highlights + +- **Getting started checklist** — A new checklist in the sidebar helps users complete initial setup. Its visibility can be controlled in settings. +- **Workspace paths in Files** — The Files view now shows the workspace path, making it easier to identify the folder currently being explored. +- **Script-bundle automation installs** — Automation catalog entries can now install a bundled script along with the automation, supporting more complete automation setups. +- **LLM provider connections** — Local agent-server users can manage LLM provider connections from a dedicated interface. +- **Automation dashboard and discovery** — The automations dashboard, recommendations rail, and Add/Import flow have been updated to make finding and adding automations easier. +- **Conversation overview and commits** — Conversations now include an overview panel and a unified commits drawer, bringing key conversation information and Git commits together. + +## Improvements and fixes + +- Agent profiles are no longer silently downgraded. +- Grouped workspace views now show all folders even when pagination is in use. +- The LLM selected from the home dropdown now takes precedence over an agent profile's pinned LLM. +- The `Cmd`+`Enter` build shortcut now applies only in plan mode. +- Long skill descriptions no longer hide modal actions. +- PDF previews now render in the built-in viewer. +- Agent Canvas no longer persists ACP model selections to agent settings when profile discovery fails. +- The events socket stays alive across refetches and has a bounded handshake, improving connection reliability. +- Streaming deltas are batched so the UI can keep up with faster models. + +## Full changelog + +- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.15.0) +- [Compare v1.14.0 to v1.15.0](https://github.com/OpenHands/OpenHands/compare/v1.14.0...v1.15.0) + +### Agent Canvas 1.16.0 +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/release-notes/v1.16.0.md + +# 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) + +### Agent Canvas 1.17.0 +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/release-notes/v1.17.0.md + +# Agent Canvas 1.17.0 + +Released September 9, 2026. + +[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.17.0). + +## Highlights + +- **Apps beta** — Canvas Extensions is now called Apps in Agent Canvas. Manage trusted custom pages in `Customize > Apps`; the Canvas Extensions API and `canvas-extension.json` format remain unchanged. See [Apps (Beta)](/openhands/usage/agent-canvas/canvas-extensions). +- **Local Plan Mode Enabled** — Plan, refine, and build from a plan on a self-hosted or local Agent Server backend. +- **Conversation tags and filtering** — Add tags from a conversation row menu, show tag chips, and filter the conversation list by tags or automation name. See [Conversations](/openhands/usage/agent-canvas/conversations). +- **Cloud LLM provider connections** — Cloud backends with an organization can manage and select shared provider connections in LLM settings. + +## Improvements and Fixes + +- Workspace hooks in `.openhands/hooks.json` now load automatically when you start a local Agent Canvas conversation. See [Hooks](/openhands/usage/customization/hooks). +- Self-hosted deployments can opt out of product telemetry with `AGENT_CANVAS_DISABLE_TELEMETRY=1` (or `true`) or the `--disable-telemetry` runtime flag. +- Automation permissions now distinguish viewing from managing automations. Users with view-only access can still manage automations they created. + +## Full Changelog + +- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.17.0) +- [Compare v1.16.0 to v1.17.0](https://github.com/OpenHands/OpenHands/compare/v1.16.0...v1.17.0) + ### Install Agent Canvas Source: https://docs.openhands.dev/openhands/usage/agent-canvas/setup.md 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. - Agent Server and ACP processes can run shell commands, read files, write files, and use connected tools. Agent Canvas is the client and does not provide isolation. Treat the machine, container, or sandbox where the backend runs as trusted infrastructure. Before exposing backend services to a network you do not control, review [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). + 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). ## Choose An Install Method @@ -32224,7 +33750,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. @@ -32248,6 +33774,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 @@ -32505,7 +34037,7 @@ If you changed the port with `--port`, use the port you selected. ## Model Or API Key Errors -If a conversation fails before the agent responds, check `Settings > LLM`. +If a conversation fails before the agent responds, check `Settings > LLM`. To choose the right provider, local endpoint, LiteLLM proxy, OpenRouter, or ACP path, start with [Configure a Model](/openhands/usage/agent-canvas/model-configuration). Common causes: @@ -32515,6 +34047,11 @@ Common causes: - A LiteLLM proxy token is invalid. - An OpenAI-compatible provider needs the provider, model, base URL, and key to line up. +Agent Canvas classifies conversation errors and presents them with distinct banner variants: + +- **Recoverable errors** (such as authentication failures) are shown with a warning banner, indicating you can take action — for example, updating an API key or switching models. +- **Internal errors** are shown with an error banner, indicating a problem that may require restarting the conversation or backend. + For model setup details, see: - [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) @@ -32660,7 +34197,7 @@ https://github.com/OpenHands/OpenHands/assets/38853559/f592a192-e86c-4f48-ad31-d _Example of CodeActAgent with `gpt-4-turbo-2024-04-09` performing a data science task (linear regression)_. -### Sandbox Server REST API (V1) +### REST API (V1) Source: https://docs.openhands.dev/openhands/usage/api/v1.md The [OpenHands Sandbox Server](https://github.com/OpenHands/sandbox-server) is the standalone API and sandbox control plane extracted from the former OpenHands monorepo. It exposes conversation and sandbox resources without bundling a frontend. @@ -32675,7 +34212,7 @@ Sandbox Server V1 REST endpoints are mounted under: - /api/v1 -Use these endpoints to integrate with the Sandbox Server control plane. Agent Canvas is the browser client for compatible deployments; Sandbox Server itself does not include a frontend. +Use these endpoints to integrate with the Sandbox Server control plane. Sandbox Server itself does not include a frontend. ## Key resources @@ -32741,7 +34278,7 @@ When asking OpenHands to create an automation, include: - **What it should do**: Describe the task clearly - **When it should run**: Daily, weekly, every hour, etc. - **Timezone** (optional): Defaults to UTC if not specified -- **Run timeout** (optional): Defaults to 10 minutes; maximum 30 minutes +- **Run timeout** (optional): Defaults to 10 minutes; the maximum depends on your deployment - **Name** (optional): The agent can suggest one based on your description - **Plugins** (optional): Mention specific plugins if you need extended capabilities @@ -33166,7 +34703,7 @@ Update the "Weekly Cleanup" automation to run on Sundays at 2 AM UTC Set the "Weekly Cleanup" automation timeout to 20 minutes ``` -Timeouts can be up to 30 minutes. Runs that exceed their timeout fail automatically. +The maximum timeout depends on your deployment. Runs that exceed their timeout fail automatically. ## Running Manually @@ -33196,6 +34733,8 @@ Each run creates a conversation that automatically appears in your conversations - **Continue** if you want to interact with the sandbox - **Debug** if something went wrong +In an automation's `Activity Log`, use `Export JSON` or `Export CSV` to download its complete run history. + Automations are user-scoped, so all your automation runs appear alongside your regular conversations. Look for them in your conversations list after each scheduled run. @@ -36393,74 +37932,97 @@ AWS Bedrock provides access to foundation models from Amazon and third-party pro ### Environment Variables -When running OpenHands with Docker, set the following environment variables using `-e`: +When running Agent Canvas with the [official Docker image](/openhands/usage/agent-canvas/backend-setup/docker), add these options to the documented `docker run` command: ```bash -docker run -it --pull=always \ - -e LLM_AWS_ACCESS_KEY_ID="your-access-key-id" \ - -e LLM_AWS_SECRET_ACCESS_KEY="your-secret-access-key" \ - -e LLM_AWS_REGION_NAME="us-east-1" \ - ... +--env LLM_AWS_ACCESS_KEY_ID="your-access-key-id" \ +--env LLM_AWS_SECRET_ACCESS_KEY="your-secret-access-key" \ +--env LLM_AWS_REGION_NAME="us-east-1" ``` +The official `ghcr.io/openhands/agent-canvas:latest` image includes the AWS SDK for Python (`boto3`). + Make sure you have enabled the Bedrock models you want to use in the AWS Console. Go to **Amazon Bedrock** → **Model access** and request access to the models you need. ### UI Configuration -In the OpenHands UI Settings under the `LLM` tab: +In Agent Canvas: -1. Enable `Advanced` options -2. Set the following: - - `Custom Model` to the Bedrock model ID (see [Model IDs](#model-ids)) - - Leave `Base URL` empty (Bedrock uses AWS endpoints automatically) - - Leave `API Key` empty (authentication is handled via AWS credentials) +1. Open `Settings > LLM` and enable the `Advanced` options. +2. Set `Custom Model` to the Bedrock model or inference profile ID. See [Model IDs](#model-ids). +3. Leave `Base URL` empty because Bedrock uses AWS endpoints automatically. +4. Leave `API Key` empty because authentication is handled through your AWS credentials. +5. Save the profile and start a new conversation to test it. + +See [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) for more information about profile settings. ### Model IDs Bedrock model IDs are managed by AWS and may change over time. Use the exact **Model ID** from the AWS Console or the AWS documentation (no `bedrock/` prefix). Example format: + - `Custom Model`: `anthropic.claude-3-5-sonnet-20241022-v2:0` For a complete list of available models, see the [AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html). ### Cross-Region Inference -Some Bedrock models can be invoked across regions by prefixing the model ID with the target region (for example, `us.`): +Some models must be invoked through a cross-region inference profile rather than their direct foundation model ID. Inference profile IDs include a geographic prefix such as `us.`. + +For example, use: + +- `Custom Model`: `us.anthropic.claude-sonnet-4-5-20250929-v1:0` + +instead of the direct model ID: -- `Custom Model`: `.` +- `anthropic.claude-sonnet-4-5-20250929-v1:0` -No additional environment variable configuration is needed—keep using your normal Bedrock setup and credentials. +No additional environment variables are required. Keep using the AWS region where you configured Bedrock access and your existing credentials. See [Increase throughput with cross-region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) for supported profiles and regions. ### Using IAM Roles (Alternative to Access Keys) -If running OpenHands on AWS infrastructure (EC2, ECS, Lambda), you can use IAM roles instead of access keys: +If running OpenHands on AWS infrastructure such as EC2, ECS, or Lambda, you can use IAM roles instead of access keys: -1. Attach an IAM role with Bedrock permissions to your compute resource -2. Omit the `LLM_AWS_ACCESS_KEY_ID` and `LLM_AWS_SECRET_ACCESS_KEY` environment variables -3. The AWS SDK will automatically use the instance role credentials +1. Attach an IAM role with Bedrock permissions to your compute resource. +2. Omit the `LLM_AWS_ACCESS_KEY_ID` and `LLM_AWS_SECRET_ACCESS_KEY` environment variables. +3. The AWS SDK automatically uses the instance role credentials. ### Troubleshooting #### "No module named 'boto3'" Error If you encounter this error: -``` + +```text litellm.APIConnectionError: No module named 'boto3' ModuleNotFoundError: No module named 'boto3' ``` -This means you're using an older version of the OpenHands Docker image that doesn't include the AWS SDK. Update to the latest version: +First identify how you installed Agent Canvas: -```bash -docker pull docker.openhands.dev/openhands/openhands:latest +- **Docker:** The current `ghcr.io/openhands/agent-canvas:latest` image includes `boto3`. Pull the latest image and recreate the container: + + ```bash + docker pull ghcr.io/openhands/agent-canvas:latest + ``` + +- **npm or npx:** The Python environment managed by the npm distribution may not include the optional Bedrock dependency. Follow [OpenHands issue #16578](https://github.com/OpenHands/OpenHands/issues/16578) for the package fix. Use the official Agent Canvas Docker image if you need Bedrock while that issue remains open. + +Do not install `boto3` into a temporary uv archive environment because Agent Canvas may recreate that environment. + +#### On-Demand Throughput Is Not Supported + +Some foundation model IDs cannot be invoked directly and return an error similar to: + +```text +Invocation of model ID ... with on-demand throughput isn't supported. +Retry your request with the ID or ARN of an inference profile that contains this model. ``` - -This issue is resolved in recent OpenHands releases. If you still see it, upgrade to `latest` (or a recent release tag). - +Use the corresponding inference profile ID or ARN, such as `us.anthropic.claude-sonnet-4-5-20250929-v1:0`. This error does not indicate a credential, model access, or `boto3` problem. #### Access Denied Errors @@ -36819,6 +38381,20 @@ page focuses on how the OpenHands interfaces surface those capabilities. When in for the canonical list of supported parameters. +## Choose a Model Configuration Path + +Choose the path that matches the access you have: + +| I have | Start here | +|---|---| +| An API key from a model provider or OpenHands | [Configure a Model in Agent Canvas](/openhands/usage/agent-canvas/model-configuration) | +| A local model server such as Ollama, LM Studio, vLLM, or SGLang | [Run Local LLMs with OpenHands](/openhands/usage/llms/local-llms) | +| A LiteLLM proxy | [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy) | +| An OpenRouter API key | [Use OpenRouter with OpenHands](/openhands/usage/llms/openrouter) | +| Claude Code, Codex, or Gemini CLI credentials | [ACP Agents](/openhands/usage/agent-canvas/acp-agents) | + +For model-ID, endpoint, API-key, and recovery checks, use [Configure a Model](/openhands/usage/agent-canvas/model-configuration) before changing advanced settings. + ## Model Recommendations Model quality for coding agents changes quickly. These recommendations are based on current @@ -36955,6 +38531,17 @@ Source: https://docs.openhands.dev/openhands/usage/llms/local-llms.md Use this guide when you want a local model, rather than a local Agent Canvas backend or local project files. Local LLMs can have limited functionality; use a capable model and GPU-backed server for the best experience. +## Choose What You Mean by Local + +| If you want... | Start here | +|---|---| +| A model server on your computer or network | Continue with this guide. | +| Agent Canvas itself to run on your computer | [Install Agent Canvas](/openhands/usage/agent-canvas/setup) | +| A containerized Agent Canvas backend | [Use Docker with Agent Canvas](/openhands/usage/agent-canvas/backend-setup/docker) | +| The agent to work with local files | [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) | + +For the model ID, base URL, and recovery checks that connect a local server to Agent Canvas, see [Configure a Model](/openhands/usage/agent-canvas/model-configuration). + ## News - 2026/05/21: We now recommend [Qwen3.6-35B-A3B](https://huggingface.co/Qwen/Qwen3.6-35B-A3B) as the first local model to try with OpenHands. It is an open-weight MoE model built for agentic coding, supports a large context window, and is available through LM Studio, Ollama, vLLM, and SGLang. @@ -37401,18 +38988,36 @@ Pricing follows official API provider rates. Below are the current pricing detai **Note:** Prices listed reflect provider rates with no markup, sourced via LiteLLM’s model price database and provider pricing pages. Cached input tokens are charged at a reduced rate when the same content is reused across requests. Models that don't support prompt caching show "N/A" for cached input cost. -### OpenRouter +### Use OpenRouter with OpenHands Source: https://docs.openhands.dev/openhands/usage/llms/openrouter.md -## Configuration +Use OpenRouter when you have an OpenRouter API key and want to access a model from its [model catalog](https://openrouter.ai/models). -When running OpenHands, you'll need to set the following in the OpenHands UI through the Settings under the `LLM` tab: -* `LLM Provider` to `OpenRouter` -* `LLM Model` to the model you will be using. -[Visit here to see a full list of OpenRouter models](https://openrouter.ai/models). -If the model is not in the list, enable `Advanced` options, and enter it in -`Custom Model` (e.g. openrouter/<model-name> like `openrouter/anthropic/claude-3.5-sonnet`). -* `API Key` to your OpenRouter API key. +## Configure Agent Canvas + +1. Open `Settings > LLM`. +2. In the `Basic` tab, select `OpenRouter` as the provider. +3. Select a model, enter your OpenRouter API key, and save the profile. +4. Start a new conversation and send a short message to verify the model responds. + +If the model is not in the selector, use the `Advanced` tab and enter its model ID with the `openrouter/` prefix. For example, OpenRouter model ID `anthropic/claude-3.5-sonnet` becomes: + +```text +openrouter/anthropic/claude-3.5-sonnet +``` + +Copy the current model ID from the [OpenRouter model catalog](https://openrouter.ai/models). Model availability and IDs can change, so do not rely on a previously saved identifier without checking it. + +## Fix Common Problems + +| Problem | Check | Next step | +|---|---|---| +| Model is not found | The exact OpenRouter model ID | Copy the ID from the model catalog and add the `openrouter/` prefix in `Advanced`. | +| Authentication fails | The API key | Create or copy an active OpenRouter API key, then save the profile again. | +| The model is unavailable | The selected model in the catalog | Choose an available model or check your OpenRouter account and model access. | +| The model does not complete agent tasks reliably | Model context and tool-use support | Choose a more capable model that supports the features required for your task. | + +For the broader configuration decision and local/proxy recovery paths, see [Configure a Model](/openhands/usage/agent-canvas/model-configuration). For LiteLLM's provider behavior, see [LiteLLM's OpenRouter documentation](https://docs.litellm.ai/docs/providers/openrouter). ### Configure Source: https://docs.openhands.dev/openhands/usage/run-openhands/gui-mode.md @@ -38052,6 +39657,10 @@ To override the defaults: for commits and pull requests. OpenHands will remain as a co-author. +## Getting Started Checklist + +The sidebar shows a **Getting Started** checklist after first-run onboarding. Toggle `Show getting started checklist` in `Settings > Application` to hide or show it. The setting persists across sessions. See [First Time Setup](/openhands/usage/agent-canvas/first-time-setup#getting-started-checklist) for details. + ## Sandbox Grouping Strategy The `Sandbox Grouping Strategy` setting controls where OpenHands places new @@ -38285,6 +39894,12 @@ for new conversations. Alternatively, you can click the `Add LLM Profile` button in the Available Profiles section to create a new profile directly. + +When saving a local LLM profile, the configuration is validated against the backend before it is persisted. If validation +fails (for example, an invalid API key or unavailable model), the save is blocked and the error is shown. Older backends +that do not support validation skip this check and save normally. + + ### Managing LLM Profiles You can manage your saved profiles in the `Available Profiles` section of the LLM settings page. Each profile shows: @@ -38618,7 +40233,7 @@ Other options include: In Agent Canvas, open `Customize > MCP Servers` to manage installed MCP servers. Use the control on an installed server card to disable it without deleting its configuration or saved credentials. Disabled servers are unavailable to new conversations until you enable them again. -Use the editor's delete action only when you want to remove the server configuration. Editing a disabled server does not enable it. +Adding, editing, renaming, or deleting one server does not remove saved credentials for your other servers. Use the editor's delete action only when you want to remove that server configuration. Editing a disabled server does not enable it. ## OAuth Authentication @@ -39647,6 +41262,251 @@ After creating the automation: - [GitHub Integration](/openhands/usage/cloud/github-installation) - Set up GitHub integration for OpenHands Cloud - [Skills Documentation](/overview/skills) - Learn more about OpenHands skills +### Agent-Driven Daily Workflow +Source: https://docs.openhands.dev/openhands/usage/use-cases/daily-workflow.md + +