From 1a1493db1de91bea0dbdafc2f869babf2700760b Mon Sep 17 00:00:00 2001 From: enyst <6080905+enyst@users.noreply.github.com> Date: Mon, 31 Aug 2026 03:10:10 +0000 Subject: [PATCH] docs: sync llms context files --- llms-full.txt | 4118 ++++++++++++++++++++++++++++++++++++++++++++++--- llms.txt | 27 +- 2 files changed, 3899 insertions(+), 246 deletions(-) diff --git a/llms-full.txt b/llms-full.txt index 32c7d659..170da87f 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -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 @@ -13210,6 +13389,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 +18403,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 +18430,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 +18684,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 +26170,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 +29421,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 +29455,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 +29466,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 +29492,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 +29522,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 +29546,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 @@ -29847,7 +30243,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 +30600,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 +30978,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). | +### Canvas Extensions (Beta) +Source: https://docs.openhands.dev/openhands/usage/agent-canvas/canvas-extensions.md + +Canvas Extensions let you add custom pages to Agent Canvas without changing the Agent Canvas source code. An extension can provide an integrated dashboard, project tool, or other browser interface that connects to the active Agent Server. + + + Canvas Extensions are a beta feature. The name and extension API may change as the feature develops. + + +## What Canvas Extensions Add + +The initial beta supports **custom pages**. When you enable an extension, its pages appear in the Agent Canvas sidebar and open inside the application. + +An extension page can: + +- Render a browser-based interface inside Agent Canvas +- Add nested routes below its declared page path +- Navigate to other Agent Canvas pages +- Make authenticated HTTP requests to the active Agent Server +- Read metadata about the extension and active backend + +The current beta does not support conversation tabs, arbitrary interface slots, themes, visualizer replacement, or direct Agent Server WebSocket connections. + +Canvas Extensions change the Agent Canvas interface. They are different from [skills](/overview/skills), which give agents instructions and knowledge, and [plugins](/openhands/usage/agent-canvas/plugins), which package agent capabilities and configuration. + +## Availability + +Canvas Extensions are managed by the active Agent Server and are currently available with supported local backends. They are not available when an OpenHands Cloud backend is active. + +Each backend has its own installed extensions, files, versions, and enabled states. Switching backends replaces the extensions shown in Agent Canvas. + +If `Customize > Extensions` reports that the feature is unavailable, update the Agent Server connected to Agent Canvas. A backend without the Canvas Extensions API cannot install or run extensions. + +## Install an Extension + +Open `Customize > Extensions`, then select `Add extension`. + + + + 1. Enter the Git source, such as `github:owner/repository`. + 2. Optionally enter a branch, tag, or commit in `Ref`. + 3. If the extension is not at the repository root, enter its directory in `Repo path`. + 4. Select `Add extension`. + + + 1. Enter the absolute path to the extension directory. + 2. Select `Add extension`. + + The path is resolved on the Agent Server machine. A path on the computer running your browser will not work unless that computer also runs the Agent Server and exposes the same path. + + + +One Add extension operation installs one extension package. If a repository contains several extensions, add each manifest directory separately with its own `Repo path`. + +New extensions are installed **disabled**. Review the source, resolved revision, manifest details, and contributed pages before enabling one. + +## Enable and Manage Extensions + +To run an installed extension: + +1. Open `Customize > Extensions`. +2. Find the installed extension and enable it. +3. Review and accept the trusted-code notice. +4. Open its new item in the Agent Canvas sidebar. + +You can disable an extension without restarting Agent Canvas. Its navigation items and mounted pages are removed immediately. Re-enable it to load the extension again, or uninstall it to remove the installation from the active backend. + +### Trust Model + +Enabling an extension runs its JavaScript in the same browser context as Agent Canvas. The beta does not isolate extensions in an iframe or worker and does not enforce fine-grained permissions. + +Only enable extensions whose code and resolved revision you trust. An enabled extension has the browser authority available to Agent Canvas and can use an authenticated helper to call the active Agent Server. + +## Build an Extension + +An extension is a directory containing: + +- `canvas-extension.json` at the extension root +- One self-contained browser ESM entrypoint inside that root +- Any source files or build configuration needed to produce the entrypoint + +The current package format uses manifest schema `1` and host API `1`. + +### Create the Manifest + +```json canvas-extension.json +{ + "schema_version": 1, + "name": "example-dashboard", + "display_name": "Example dashboard", + "version": "0.1.0", + "description": "A project dashboard for Agent Canvas.", + "entrypoint": "extension.js", + "contributes": { + "pages": [ + { + "id": "dashboard", + "title": "Dashboard", + "path": "/dashboard", + "nav_label": "Dashboard" + } + ] + } +} +``` + +Use lowercase letters, numbers, and hyphens for extension names and page IDs. Page paths must start with `/`, and every page ID and path must be unique within the extension. + +The `entrypoint` must stay inside the extension root. Bundle dependencies, CSS, and required assets into one browser ESM file; unresolved package imports and external runtime chunks cannot be loaded. + +### Register the Page + +Export an `activate` function from the entrypoint and register each page declared in the manifest: + +```js extension.js +export function activate(host) { + if (host.apiVersion !== "1") { + throw new Error("This extension requires host API 1."); + } + + return host.registerPage("dashboard", ({ container, path }) => { + const page = document.createElement("section"); + page.setAttribute("aria-label", "Example dashboard"); + page.textContent = path ? `Dashboard route: ${path}` : "Dashboard"; + container.append(page); + + return () => page.remove(); + }); +} +``` + +The page ID passed to `registerPage` must match a page declared in `canvas-extension.json`. Return cleanup functions for registered pages, DOM nodes, timers, listeners, and other effects so the extension can be disabled or reloaded safely. + +Agent Canvas mounts this example at: + +```text +/extensions/example-dashboard/dashboard +``` + +For a nested URL such as `/extensions/example-dashboard/dashboard/services`, the page receives `services` as its relative `path`. + +### Connect to the Agent Server + +Use `host.agentServer.request` for authenticated requests to the backend that owns the extension: + +```js +const serverInfo = await host.agentServer.request({ + method: "GET", + path: "/server_info", +}); +``` + +Request paths must be root-relative, begin with exactly one `/`, and must not be full URLs. Do not derive backend URLs or authentication credentials from Agent Canvas internals. + +The beta host API does not expose the backend origin or a WebSocket authentication capability. Use the authenticated HTTP helper, polling where appropriate, or a backend-owned bridge instead of opening a direct Agent Server WebSocket. + +## Design for the Beta Lifecycle + +Agent Canvas may activate, mount, and dispose an extension repeatedly when you enable or disable it, update it, reconnect, or switch backends. Extension pages should: + +- Render only inside the supplied page container +- Scope styles to an extension-specific root element +- Clean up all DOM nodes, styles, timers, listeners, observers, and subscriptions +- Prevent late asynchronous responses from updating an unmounted page +- Handle loading, empty, malformed-response, and error states +- Remain keyboard accessible and usable on narrow screens + +## Learn More + +- [Canvas Extensions specification](https://github.com/OpenHands/OpenHands/blob/main/specs/canvas-extensions.md) +- [Minimal extension fixture](https://github.com/OpenHands/OpenHands/tree/main/src/fixtures/canvas-extensions/demo-page) +- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) + ### 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 +31200,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 +31353,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 +31527,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) +- [Canvas Extensions (Beta)](/openhands/usage/agent-canvas/canvas-extensions) -Use the section navigation inside `Customize` to switch between these pages. +Use the section navigation inside `Customize` to switch between these pages. Canvas Extensions add trusted custom pages to Agent Canvas, while skills and plugins change agent behavior. MCP Server configuration lives under `Customize > MCP Servers`, not under `Settings`. @@ -30915,15 +31566,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 +31684,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 +31705,142 @@ 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. + + ## 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 @@ -31095,8 +31879,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 +31913,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 an 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. + +### 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 + +In the profile editor, use the **provider-connection selector** to link a profile to an existing connection. 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. + +### Broken Link Badge + +If a provider connection is deleted while still referenced by a profile, the profile shows a **Broken link** badge. Re-link the profile to another connection or restore inline credentials to resolve it. + ## Working with LLM Profiles LLM profiles are useful when you want different model setups for different tasks, such as: @@ -31131,6 +31953,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 +32007,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 +32020,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 +32090,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) @@ -31343,16 +32181,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. | - - 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. - +```mermaid +flowchart LR + browser["Browser UI"] --> backend["Selected backend"] + backend --> conversation["Conversation and agent"] + conversation --> model["Model access"] + conversation --> workspace["Workspace and tools"] + + 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. @@ -31532,7 +32381,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 +32404,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 +32773,225 @@ 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) + ### 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 +33293,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 +33317,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 @@ -32515,6 +33590,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 +33740,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 +33755,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 +33821,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 +34246,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 +34276,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 +37475,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.`. -- `Custom Model`: `.` +For example, use: -No additional environment variable configuration is needed—keep using your normal Bedrock setup and credentials. +- `Custom Model`: `us.anthropic.claude-sonnet-4-5-20250929-v1:0` + +instead of the direct model ID: + +- `anthropic.claude-sonnet-4-5-20250929-v1:0` + +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 @@ -38052,6 +39157,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 +39394,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 +39733,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 +40762,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 + +