From 3e1c8bc66b53153aa39b13e4b3ce680faef08fa8 Mon Sep 17 00:00:00 2001 From: Devin Date: Wed, 1 Jul 2026 12:42:34 -0400 Subject: [PATCH 1/6] Clarify Agent Canvas overview Rework the overview page around the first-run mental model users need before setup: when to use Agent Canvas, how the UI/backend/workspace/model pieces fit together, which trust boundary to choose, and where to go next. This addresses interview and docs-chat feedback showing confusion around Agent Canvas setup paths, backend execution, model access, and file access. --- openhands/usage/agent-canvas/overview.mdx | 103 +++++++++++++++++----- 1 file changed, 79 insertions(+), 24 deletions(-) diff --git a/openhands/usage/agent-canvas/overview.mdx b/openhands/usage/agent-canvas/overview.mdx index 68ca6737..45cadfdf 100644 --- a/openhands/usage/agent-canvas/overview.mdx +++ b/openhands/usage/agent-canvas/overview.mdx @@ -1,35 +1,90 @@ --- title: Agent Canvas Overview -description: A lightweight platform to run agents and automations — locally or in the cloud. +description: Understand Agent Canvas, how it runs agents, and which setup path to choose. --- -## Why Agent Canvas +Agent Canvas is an open-source control surface for agentic work. It gives you one browser UI for conversations, files, terminal output, model configuration, backends, and automations. -- **One UI to drive any agent**: run conversations with OpenHands, Claude Code, Codex, or Gemini CLI through the same browser interface. -- **Bring your own LLM**: connect Anthropic, OpenAI, Google, or any OpenAI-compatible provider. Switch models per conversation. -- **Built-in automations**: schedule cron jobs or wire up event-driven workflows against GitHub, Linear, Slack, and custom webhooks. -- **Run it anywhere**: a single `agent-canvas` command starts the full stack locally. Self-host on a VM, or connect to OpenHands Cloud. +By default, Agent Canvas runs on your own machine. You can also connect the same UI to backends running in Docker, on a VM, on Modal, or in [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud). -## Key Concepts +## When To Use Agent Canvas -| Concept | What It Means | -|---------|----------------| -| **Agent Canvas** | A UI and backend server for running agents and automations. The `agent-canvas` command starts both together. | -| **Backend** | Any Canvas UI can securely connect to any Canvas backend: running locally, on a remote machine, or on [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud). Register multiple and switch between them. | -| **Conversation** | A single agent session tied to a backend. Each conversation has its own message history, tool calls, and file changes. | -| **Automation** | A workflow that runs on a cron schedule or in response to events from GitHub, Linear, Slack, or custom webhooks. Automations may start agent conversations as needed. | +Use Agent Canvas when you want a self-hosted or local browser UI for agents that can work with real files, terminals, tools, and automations. -## How It Fits with Other OpenHands Products +| If you want to... | Start here | +|-------------------|------------| +| Run OpenHands locally in a browser | [Install Agent Canvas](/openhands/usage/agent-canvas/setup) | +| Use a sandboxed local environment | [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker) | +| Run agents on an always-on machine | [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) | +| Connect to managed cloud sandboxes | [Cloud Backend](/openhands/usage/agent-canvas/backend-setup/cloud) | +| Use Claude Code, Codex, Gemini CLI, or another ACP agent | [ACP Agents](/openhands/usage/agent-canvas/acp-agents) | +| Create scheduled or event-driven workflows | [Pre-built Automations](/openhands/usage/agent-canvas/prebuilt-automations) | -- **Agent Canvas**: the recommended browser-based UI for running OpenHands locally or self-hosted. -- **Local GUI (Legacy)**: legacy UI requiring Docker. -- **OpenHands Cloud**: a fully managed version of OpenHands. -- **OpenHands SDK**: the Python framework behind the agent system. +## How Agent Canvas Works -## Where to Start +Agent Canvas has four pieces to understand: -- [Install](/openhands/usage/agent-canvas/setup) — Use the published npm package to run Agent Canvas from your terminal. -- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) — Switch between local and remote backends. -- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) — Configure skills, MCP servers, and backend-synced settings. -- [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations) — Get started with a ready-made automation workflow. -- [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) — Run backend-only or full Canvas on a VM and connect remotely. +| 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. | + + + Settings, secrets, LLM configuration, MCP servers, skills, conversations, and automations are scoped to the active backend. Switching backends switches the environment the agent is using. + + +## Choosing A Trust Boundary + +Before installing, decide where you want the agent to run and what files it should be able to access. + +| Setup | Trust Boundary | Best For | +|-------|----------------|----------| +| **npm local install** | Runs directly on your machine. The agent server can operate in local workspaces you open. | Fastest local setup when you trust the machine and understand the file access. | +| **Docker** | Runs inside a container and only sees the directories you mount. | Local sandboxing and clearer file boundaries. | +| **VM or dedicated machine** | Runs on the remote host you control. | Always-on agents, heavier compute, team-shared backends, or personal/work separation. | +| **OpenHands Cloud** | Runs in managed OpenHands Cloud sandboxes. | Cloud execution without maintaining your own machine or VM backend. | + + + Agent Canvas can run agents that execute shell commands, read files, write files, and use connected tools. Only connect a backend to files, secrets, and networks that you are willing to let the agent use. + + +## Model Access + +Agent Canvas supports several model access patterns: + +- **Direct provider key** — enter an API key from Anthropic, OpenAI, Google, or another supported provider. +- **OpenHands Cloud key** — use an OpenHands Cloud API key for verified hosted models. +- **ACP agent subscription login** — use a signed-in provider, such as Claude Code, Codex, or Gemini, when the backend runs on the same machine as that login. +- **Local or OpenAI-compatible provider** — connect providers such as Ollama, LM Studio, LiteLLM, or a compatible gateway through model settings. + +See [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles) and [ACP Agents](/openhands/usage/agent-canvas/acp-agents) for details. + +## How It Fits With Other OpenHands Products + +| Product | Use It When | +|---------|-------------| +| **Agent Canvas** | You want a self-hosted browser UI for local, remote, or cloud-backed agents and automations. | +| **OpenHands Cloud** | You want a fully managed hosted experience with no local installation. | +| **OpenHands SDK** | You want to build agents or agent-powered applications in Python. | +| **Local GUI (Legacy)** | You are following older Docker-based Local GUI documentation. New local browser workflows should use Agent Canvas. | + +## Before You Start + +For the normal local setup, you need: + +- Node.js 22.12 or later +- `npm` +- A model access path, such as a provider API key, OpenHands Cloud key, ACP subscription login, or local model server +- A folder, repository, or project workspace for the agent to work in + +For a sandboxed local setup, use Docker instead of the direct npm backend path. + +## Where To Go Next + +- [Install Agent Canvas](/openhands/usage/agent-canvas/setup) +- [First Time Setup](/openhands/usage/agent-canvas/first-time-setup) +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles) +- [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting) From 6f6c99730512d2c9d02eebdab80b8385715c9eb9 Mon Sep 17 00:00:00 2001 From: Devin Date: Wed, 1 Jul 2026 13:47:51 -0400 Subject: [PATCH 2/6] Expand Agent Canvas install lifecycle docs Rework the setup page from a short install reference into a full lifecycle guide. The page now helps users choose npm, Docker, VM/self-hosted, or source workflows; verify prerequisites; start and confirm the local UI; understand common flags and environment variables; and stop, update, or uninstall Agent Canvas. This targets setup and uninstall confusion surfaced in interview feedback and docs-chat analysis. --- openhands/usage/agent-canvas/setup.mdx | 231 ++++++++++++++++++++----- 1 file changed, 183 insertions(+), 48 deletions(-) diff --git a/openhands/usage/agent-canvas/setup.mdx b/openhands/usage/agent-canvas/setup.mdx index f05cd008..00501eb3 100644 --- a/openhands/usage/agent-canvas/setup.mdx +++ b/openhands/usage/agent-canvas/setup.mdx @@ -1,56 +1,90 @@ --- title: Install -description: Install and run Agent Canvas via npm or Docker. +description: Install, run, update, and uninstall Agent Canvas. --- +Agent Canvas can run directly on your machine or inside Docker. Start with the simplest setup that matches the trust boundary you want. + - Agent Canvas starts an agent server on the machine where you run it. Treat that machine as trusted infrastructure and review the guidance in [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) before exposing it to a network you do not control. + Agent Canvas starts an agent server that can run shell commands, read files, write files, and use connected tools. Treat the machine or container where the backend runs as trusted infrastructure. Before exposing Agent Canvas to a network you do not control, review [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). +## Choose An Install Method + +| Method | Use It When | What The Agent Can Access | +|--------|-------------|---------------------------| +| **npm local install** | You want the quickest local browser setup. | Runs directly on your machine and can work in local workspaces you open. | +| **Docker** | You want a local sandbox with clearer file boundaries. | Runs inside a container and can access mounted project directories. | +| **VM / self-hosted** | You want an always-on backend, stronger hardware, or a team-accessible server. | Runs on the VM or dedicated host you configure. | +| **From source** | You are contributing to Agent Canvas or changing the frontend/backend stack. | Runs your local development checkout. | + + + If you are new to Agent Canvas, use the npm local install first unless you specifically want Docker sandboxing. + + +## Verify Prerequisites + - **Prerequisites:** [Node.js](https://nodejs.org/en/download) 22.12 or later, `npm`, and [`uv`](https://docs.astral.sh/uv/getting-started/installation/). + Install [Node.js](https://nodejs.org/en/download) 22.12 or later and [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then verify both tools are available: - **Install:** ```bash - npm install -g @openhands/agent-canvas + node --version + npm --version + uv --version ``` - **Run:** + If `uv` or `uvx` is missing, install `uv` before starting Agent Canvas. The local agent server runtime uses it. + + + + Install [Docker](https://docs.docker.com/get-docker/) and make sure the Docker daemon is running: + ```bash - agent-canvas + docker --version + docker ps ``` - By default, Agent Canvas starts on `http://localhost:8000`. + On macOS and Windows, open Docker Desktop before running the container. + + - ### CLI Flags + + Termux and other mobile Linux environments are not a primary supported target. For the most reliable local setup, use macOS, Linux, Windows with PowerShell, or Windows with WSL2. + - | Flag | Description | - |------|-------------| - | `-p`, `--port ` | Set the ingress port (default `8000`) | - | `--public` | Enable public mode — requires `LOCAL_BACKEND_API_KEY`. The key is **not** injected into the frontend; users must enter it when the UI loads. Use this for any deployment reachable by others. See [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). | - | `--backend-only` | Start only the backend behind ingress (no frontend). Use this to run a headless backend on a VM or server. | - | `--frontend-only` | Start only the static frontend behind ingress (no agent server or automation). Use this to point a local UI at a remote backend. | - | `-v`, `--version` | Show the version number | - | `--info` | Show the version and default stack configuration (agent server version, ports, etc.) | - | `-h`, `--help` | Show the built-in help output | +## Install And Run - ### Environment Variables + + + Install the published package globally: - | Variable | Purpose | - |----------|---------| - | `LOCAL_BACKEND_API_KEY` | API key for the server. Required in `--public` mode; optional otherwise (auto-generated and persisted across restarts). | - | `OH_SECRET_KEY` | Secret used to protect stored settings and secrets | - | `OH_AGENT_SERVER_VERSION` | Pin a specific agent server version (e.g. `0.1.0`) | - - - **Prerequisites:** [Docker](https://docs.docker.com/get-docker/) (Docker Desktop on macOS/Windows, or Docker Engine on Linux). + ```bash + npm install -g @openhands/agent-canvas + ``` - A Docker image is available that sandboxes the entire Agent Canvas stack. Mount your project files and a persistence directory for settings, secrets, and conversation history. + Start the full local stack: - Create a host directory for your projects (the agent can access any folder under this path) and run the container: + ```bash + agent-canvas + ``` + + Agent Canvas starts on `http://localhost:8000` by default. If your browser does not open automatically, open that URL manually. + + + You can also run the latest package without a global install: + + ```bash + npx @openhands/agent-canvas + ``` + + + + + Create host directories for persistent settings and project files, then start the container. **macOS / Linux:** + ```bash mkdir -p ~/projects ~/.openhands @@ -62,6 +96,7 @@ description: Install and run Agent Canvas via npm or Docker. ``` **Windows (PowerShell):** + ```powershell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openhands", "$env:USERPROFILE\projects" | Out-Null @@ -72,38 +107,138 @@ description: Install and run Agent Canvas via npm or Docker. ghcr.io/openhands/agent-canvas:latest ``` + Agent Canvas starts on `http://localhost:8000`. The agent can access project files under the mounted `/projects` directory. + - On Windows, Docker Desktop must be installed and running. PowerShell uses backticks (`` ` ``) for line continuation instead of backslashes. + PowerShell uses backticks (`` ` ``) for line continuation. If Docker reports that it cannot connect to the daemon, start Docker Desktop and run the command again. + - ### Environment Variables + + Use the source workflow only when you want to modify Agent Canvas itself: - Configuration is passed via `-e` flags on `docker run`: + ```bash + git clone https://github.com/OpenHands/agent-canvas.git + cd agent-canvas + npm install + npm run dev + ``` - | Variable | Purpose | - |----------|---------| - | `PORT` | Ingress port inside the container (default `8000`). Map it with `-p :`. | - | `LOCAL_BACKEND_API_KEY` | API key for the server. Auto-generated and persisted if not set. | - | `OH_SECRET_KEY` | Secret used to protect stored settings and secrets | + For development-specific environment variables and commands, see [Contribute / Development](/openhands/usage/agent-canvas/development). - - If you want to clone the repository, run custom dev modes, or configure Vite-specific environment variables, use the [Contribute / Development guide](/openhands/usage/agent-canvas/development) instead. - +## Confirm It Started + +After startup: + +1. Open `http://localhost:8000`. +2. Confirm the default local backend shows as connected. +3. Open `Settings > LLM` and configure a model access path. +4. Choose `Open Workspace` before starting a conversation if you want the agent to work in a specific folder. +5. Return to the home screen and start a conversation. + +If the page does not load, check the terminal where Agent Canvas is running. Common causes are a missing prerequisite, a busy port, or Docker not running. + +## Common Startup Options + +| Option | Description | +|--------|-------------| +| `-p`, `--port ` | Set the ingress port. The default is `8000`. | +| `--backend-only` | Start only the backend behind ingress. Use this for a headless backend on a local machine, VM, or server. | +| `--frontend-only` | Start only the static frontend behind ingress. Use this when connecting a local UI to a remote backend. | +| `--public` | Enable public mode. Requires `LOCAL_BACKEND_API_KEY` and is intended for deployments reachable beyond localhost. | +| `-v`, `--version` | Show the version number. | +| `--info` | Show version and stack configuration details. | +| `-h`, `--help` | Show built-in help. | + +If port `8000` is already in use, start Agent Canvas on another port: -## First Steps After Launch +```bash +agent-canvas --port 3000 +``` -After the UI opens: +## Environment Variables + +| Variable | Purpose | +|----------|---------| +| `LOCAL_BACKEND_API_KEY` | API key for the server. Required in `--public` mode; optional for local use because Agent Canvas can auto-generate and persist one. | +| `OH_SECRET_KEY` | Secret used to protect stored settings and secrets. | +| `OH_AGENT_SERVER_VERSION` | Pin a specific agent server version, such as `0.1.0`. | +| `PORT` | Ingress port inside the Docker container. Map it with `-p :`. | + +## Stop Agent Canvas + + + + Return to the terminal running Agent Canvas and press `Ctrl+C`. + + + + Return to the terminal running the container and press `Ctrl+C`. + + If the container is running in the background, stop it with: + + ```bash + docker ps + docker stop + ``` + + + +## Update Agent Canvas + + + + Stop Agent Canvas, then reinstall the latest package: + + ```bash + npm install -g @openhands/agent-canvas@latest + agent-canvas --version + ``` + + + + Stop the running container, pull the latest image, then run the container again: + + ```bash + docker pull ghcr.io/openhands/agent-canvas:latest + ``` + + + +Your settings and conversation data are stored outside the package or image when you use the documented `~/.openhands` mount. + +## Uninstall Agent Canvas + + + + Stop any running Agent Canvas process, then uninstall the package: + + ```bash + npm uninstall -g @openhands/agent-canvas + ``` + + If Windows reports that `uv.exe` or another file is in use, close terminals running Agent Canvas, stop related processes, and run the uninstall command again. + + + + Stop any running container, then remove the image if you no longer need it: + + ```bash + docker ps + docker stop + docker rmi ghcr.io/openhands/agent-canvas:latest + ``` + + -1. Confirm the default local backend is healthy. -2. Open `Settings > LLM` and configure a provider, model, and API key. -3. Open `Customize` if you want to add skills or MCP servers. -4. Return to the home screen and enter a prompt to start your first conversation. -5. If you want the conversation tied to a local folder, choose `Open Workspace` first. +Uninstalling the package or image does not automatically remove your persisted data. If you want to delete local settings, secrets, and conversation history, remove the persistence directory you mounted or used, such as `~/.openhands`. ## Next Steps +- [First Time Setup](/openhands/usage/agent-canvas/first-time-setup) - [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) - [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles) -- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) +- [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker) +- [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting) From e36ad203bdbbd32c82794eec6b509239722b30ee Mon Sep 17 00:00:00 2001 From: Devin Date: Mon, 6 Jul 2026 10:33:37 -0400 Subject: [PATCH 3/6] Add more exhaustive troubleshooting and npx as an install option --- openhands/usage/agent-canvas/setup.mdx | 60 +++- .../usage/agent-canvas/troubleshooting.mdx | 323 ++++++++++++++++-- 2 files changed, 352 insertions(+), 31 deletions(-) diff --git a/openhands/usage/agent-canvas/setup.mdx b/openhands/usage/agent-canvas/setup.mdx index 00501eb3..151b989c 100644 --- a/openhands/usage/agent-canvas/setup.mdx +++ b/openhands/usage/agent-canvas/setup.mdx @@ -15,16 +15,18 @@ Agent Canvas can run directly on your machine or inside Docker. Start with the s |--------|-------------|---------------------------| | **npm local install** | You want the quickest local browser setup. | Runs directly on your machine and can work in local workspaces you open. | | **Docker** | You want a local sandbox with clearer file boundaries. | Runs inside a container and can access mounted project directories. | +| **npx** | You want to try Agent Canvas without installing the package globally. | Runs directly on your machine and can work in local workspaces you open. | | **VM / self-hosted** | You want an always-on backend, stronger hardware, or a team-accessible server. | Runs on the VM or dedicated host you configure. | | **From source** | You are contributing to Agent Canvas or changing the frontend/backend stack. | Runs your local development checkout. | - If you are new to Agent Canvas, use the npm local install first unless you specifically want Docker sandboxing. + If you are new to Agent Canvas, use `npx` for a quick first run or npm local install if you want a reusable `agent-canvas` command. Use Docker when you specifically want sandboxing. ## Verify Prerequisites + Install [Node.js](https://nodejs.org/en/download) 22.12 or later and [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then verify both tools are available: @@ -47,6 +49,19 @@ Agent Canvas can run directly on your machine or inside Docker. Start with the s On macOS and Windows, open Docker Desktop before running the container. + + + Install [Node.js](https://nodejs.org/en/download) 22.12 or later and [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then verify the tools are available: + + ```bash + node --version + npm --version + uv --version + ``` + + If `uv` or `uvx` is missing, install `uv` before starting Agent Canvas. The local agent server runtime uses it. + + @@ -56,6 +71,7 @@ Agent Canvas can run directly on your machine or inside Docker. Start with the s ## Install And Run + Install the published package globally: @@ -70,14 +86,6 @@ Agent Canvas can run directly on your machine or inside Docker. Start with the s ``` Agent Canvas starts on `http://localhost:8000` by default. If your browser does not open automatically, open that URL manually. - - - You can also run the latest package without a global install: - - ```bash - npx @openhands/agent-canvas - ``` - @@ -113,6 +121,18 @@ Agent Canvas can run directly on your machine or inside Docker. Start with the s PowerShell uses backticks (`` ` ``) for line continuation. If Docker reports that it cannot connect to the daemon, start Docker Desktop and run the command again. + + Run the latest published package without installing it globally: + + ```bash + npx @openhands/agent-canvas + ``` + + Agent Canvas starts on `http://localhost:8000` by default. If your browser does not open automatically, open that URL manually. + + Use `npx` when you want to try Agent Canvas once, avoid global package installs, or work around a shell `PATH` issue with the global `agent-canvas` command. + + Use the source workflow only when you want to modify Agent Canvas itself: @@ -170,6 +190,10 @@ agent-canvas --port 3000 ## Stop Agent Canvas + + Return to the terminal running Agent Canvas and press `Ctrl+C`. + + Return to the terminal running Agent Canvas and press `Ctrl+C`. @@ -189,6 +213,14 @@ agent-canvas --port 3000 ## Update Agent Canvas + + Stop Agent Canvas, then run the latest package: + + ```bash + npx @openhands/agent-canvas@latest + ``` + + Stop Agent Canvas, then reinstall the latest package: @@ -212,6 +244,16 @@ Your settings and conversation data are stored outside the package or image when ## Uninstall Agent Canvas + + There is no Agent Canvas package to uninstall when you use `npx`. Stop the running process with `Ctrl+C`. + + If you want to clear downloaded package cache entries, use npm's cache commands: + + ```bash + npm cache verify + ``` + + Stop any running Agent Canvas process, then uninstall the package: diff --git a/openhands/usage/agent-canvas/troubleshooting.mdx b/openhands/usage/agent-canvas/troubleshooting.mdx index a55d9cc4..57145605 100644 --- a/openhands/usage/agent-canvas/troubleshooting.mdx +++ b/openhands/usage/agent-canvas/troubleshooting.mdx @@ -1,48 +1,276 @@ --- title: Troubleshooting -description: Common Agent Canvas setup and runtime issues, plus places to ask for help. +description: Fix common Agent Canvas install, startup, backend, model, workspace, and uninstall issues. --- -Use this page for the most common Agent Canvas problems. +Use this page when Agent Canvas does not start, the browser cannot reach it, the backend is disconnected, model setup fails, or uninstall/update commands get stuck. -## Command Not Found +## Start With These Checks + +Run the checks for the install method you used: + + + + ```bash + node --version + npm --version + uv --version + agent-canvas --help + ``` + + If one command fails, fix that prerequisite first. See [Install](/openhands/usage/agent-canvas/setup). + + + + ```bash + docker --version + docker ps + ``` + + If `docker ps` cannot connect to the Docker daemon, start Docker Desktop or Docker Engine and try again. + + + +## `agent-canvas` Command Not Found If `agent-canvas` is not available after installation: -- confirm the package installed successfully with `npm install -g @openhands/agent-canvas` -- make sure your npm global bin directory is on your `PATH` -- run `agent-canvas --help` to confirm the binary resolves correctly +1. Confirm the package installed successfully. You should see `@openhands/agent-canvas` followed by the version if it has been installed: + + ```bash + npm list -g --depth 0 + ``` + +2. Check your npm global install prefix: + + ```bash + npm prefix -g + ``` + +3. Make sure the npm global `bin` directory is on your `PATH`. + + + + Find the npm global `bin` directory: + + ```bash + echo "$(npm prefix -g)/bin" + ``` + + Check whether your shell can already find `agent-canvas`: + + ```bash + which agent-canvas + ``` + + If `which agent-canvas` prints nothing, check your current `PATH`: + + ```bash + echo "$PATH" + ``` + + If the npm global `bin` directory is missing, add it for the current terminal session: + + ```bash + export PATH="$(npm prefix -g)/bin:$PATH" + ``` + + To make the change permanent, add that `export` line to your shell profile, such as `~/.zshrc` or `~/.bashrc`. + + + + Find the npm global install prefix: + + ```powershell + npm prefix -g + ``` + + Check whether PowerShell can already find `agent-canvas`: + + ```powershell + Get-Command agent-canvas + ``` + + If `Get-Command` cannot find it, inspect your current `PATH`: + + ```powershell + $env:Path -split ';' + ``` -## Missing `uv` + The npm global package directory, or the `bin` directory for your Node.js installation, needs to appear in that list. + + -Agent Canvas relies on `uv` to run the local agent server stack. +4. Try running without a global install: -If startup fails because `uv` or `uvx` is missing, install it from the official guide: + ```bash + npx @openhands/agent-canvas + ``` -- [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) +If `npx` works but `agent-canvas` does not, the issue is usually your shell `PATH`. -## Port Already in Use +## Missing `uv` Or `uvx` -Agent Canvas listens on port `8000` by default. If that port is busy, start it on another one: +Agent Canvas uses `uv` to run the local agent server stack. + +If startup fails because `uv` or `uvx` is missing: + +1. Install `uv` from the [official uv installation guide](https://docs.astral.sh/uv/getting-started/installation/). +2. Open a new terminal so your shell reloads its `PATH`. +3. Verify the install: + + ```bash + uv --version + ``` + +4. Start Agent Canvas again: + + ```bash + agent-canvas + ``` + +## Browser Does Not Open Or Shows A Blank Page + +Agent Canvas listens on `http://localhost:8000` by default. + +If nothing opens automatically: + +1. Open `http://localhost:8000` manually. +2. Check the terminal running Agent Canvas for startup errors. +3. If port `8000` is busy, start on another port: + + ```bash + agent-canvas --port 3000 + ``` + +4. Open `http://localhost:3000`. + +If the browser page loads but stays blank, refresh once and check the terminal for frontend or backend startup errors. + +## Port Already In Use + +If startup says port `8000` is already in use, run Agent Canvas on another port: ```bash agent-canvas --port 3000 ``` +If you are using Docker, map a different host port: + +```bash +docker run -it --rm \ + -p 3000:8000 \ + -v ~/.openhands:/home/openhands/.openhands \ + -v ~/projects:/projects \ + ghcr.io/openhands/agent-canvas:latest +``` + +Then open `http://localhost:3000`. + +## Docker Daemon Not Running + +If Docker commands fail with a daemon or connection error: + +1. Start Docker Desktop on macOS or Windows, or start Docker Engine on Linux. +2. Verify Docker is running: + + ```bash + docker ps + ``` + +3. Run the Agent Canvas Docker command again. + +On Windows, use PowerShell command syntax from [Install](/openhands/usage/agent-canvas/setup#install-and-run). PowerShell uses backticks (`` ` ``) for line continuation instead of backslashes. + ## Backend Is Unreachable -If Agent Canvas cannot talk to the active backend: +If Agent Canvas loads but the active backend is disconnected: -- open `Manage Backends` -- verify the backend host or base URL -- verify the API key if the backend requires one -- switch to another backend to confirm the issue is backend-specific +1. Open the backend switcher and select `Manage Backends`. +2. Verify the backend host URL. +3. Verify the API key if the backend requires one. +4. Switch to the default local backend if available. +5. Check the terminal or server logs for backend startup errors. -## LLM Profiles Do Not Match OpenHands Cloud +For the default local setup, you usually do not need to manually enter a backend API key. Agent Canvas can generate and persist one locally. -Agent Canvas currently has fuller support for LLM profiles than the hosted OpenHands Cloud UI. +For `--public`, VM, Modal, or other remote backends, use the `LOCAL_BACKEND_API_KEY` configured for that backend. Anyone with that key can access the backend, so keep it private. -If profiles appear in Agent Canvas but not in OpenHands Cloud directly, that can be expected while the Cloud rollout is still in progress. +## Wrong Backend URL Or API Key + +Backend URLs should point to the Agent Canvas backend ingress, not to an unrelated local service. + +Common examples: + +| Setup | Typical URL | +|-------|-------------| +| Default local Agent Canvas | `http://localhost:8000` | +| Local backend on another port | `http://localhost:8001` | +| Docker mapped to host port `8000` | `http://localhost:8000` | +| VM or reverse proxy | Your VM, proxy, or ngrok URL | + +If you changed the port with `--port`, use the port you selected. + +## Model Or API Key Errors + +If a conversation fails before the agent responds, check `Settings > LLM`. + +Common causes: + +- The API key is missing or expired. +- The selected provider does not match the model name. +- A custom or local model is missing the correct base URL. +- A LiteLLM proxy token is invalid. +- An OpenAI-compatible provider needs the provider, model, base URL, and key to line up. + +For model setup details, see: + +- [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles) +- [LLM Settings](/openhands/usage/settings/llm-settings) +- [Local LLMs](/openhands/usage/llms/local-llms) +- [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy) + +## `LLM Provider NOT provided` + +This error usually means the configured model name does not include enough provider information, or the provider field is not set. + +Fix it by opening `Settings > LLM` and confirming: + +1. The `LLM Provider` field is set. +2. The model ID matches that provider. +3. Any custom `Base URL` is correct for the provider or local model server. +4. The API key or token is valid. + +If you are using Ollama, LM Studio, LiteLLM, or another OpenAI-compatible endpoint, use the provider and base URL expected by that service. See [Local LLMs](/openhands/usage/llms/local-llms). + +## ACP Agent Credentials Are Not Used + +ACP agents such as Claude Code, Codex, and Gemini CLI can be used in place of an LLM API key. + +If an ACP agent does not authenticate: + +1. Confirm the provider CLI is signed in on the same machine where the backend runs. +2. If the backend runs in Docker, on a VM, or in cloud infrastructure, do not assume it can see your laptop's CLI login. +3. Add the required API key or secret for that backend. +4. Reopen or restart the conversation after changing agent settings. + +See [ACP Agents](/openhands/usage/agent-canvas/acp-agents) for the credential rules. + +## Workspace Is Not Where You Expected + +The agent works in the workspace attached to the conversation. + +If file changes appear in the wrong place or the agent cannot find your project: + +1. Use `Open Workspace` before starting the conversation. +2. Confirm the conversation is using the backend you expect. +3. For Docker, make sure the project is under the mounted projects directory, such as `~/projects`, which appears as `/projects` inside the container. +4. For a VM backend, remember that the agent sees files on the VM, not files on your laptop. +5. For a cloud backend, use the cloud workspace or repository flow for that backend. + + + Do not expose broad filesystem mounts or sensitive directories unless you are comfortable with the agent reading and writing files there. + ## MCP Settings Are Missing @@ -50,11 +278,62 @@ MCP configuration does not live under `Settings`. Open the top-level `Customize` area, then go to `MCP Servers`. +If a configured MCP server is not available to the agent: + +1. Confirm it is saved on the active backend. +2. Confirm any required secrets are saved under `Settings > Secrets`. +3. Restart or start a new conversation if the server was added after the conversation began. + ## Automation Features Are Unavailable -If the `Automations` view shows an unavailable or unhealthy state, the active backend may not have a working automation service. +Automations run on the active backend. + +If the `Automations` view shows an unavailable or unhealthy state: + +1. Switch to the default local backend and check whether automations work there. +2. Confirm the remote backend includes the automation service. +3. Check the backend logs for automation startup errors. +4. Confirm required MCP servers and secrets are configured on the same backend as the automation. + +See [Pre-built Automations](/openhands/usage/agent-canvas/prebuilt-automations). + +## LLM Profiles Do Not Match OpenHands Cloud + +Agent Canvas currently has fuller support for LLM profiles than the hosted OpenHands Cloud UI. + +If profiles appear in Agent Canvas but not in OpenHands Cloud directly, that can be expected while the Cloud rollout is still in progress. + +Profiles and settings are also scoped to the active backend, so switching backends can change which profiles are available. + +## Update Or Uninstall Is Stuck + +Before updating or uninstalling, stop Agent Canvas. + + + + Stop the running process with `Ctrl+C`, then update or uninstall: + + ```bash + npm install -g @openhands/agent-canvas@latest + npm uninstall -g @openhands/agent-canvas + ``` + + On Windows, if uninstall fails because `uv.exe` or another file is in use, close terminals running Agent Canvas, stop related processes, and retry. + + + + Stop the container before updating or removing the image: + + ```bash + docker ps + docker stop + docker pull ghcr.io/openhands/agent-canvas:latest + docker rmi ghcr.io/openhands/agent-canvas:latest + ``` + + -Start with the default local backend to confirm the UI works, then debug the remote backend separately. +Uninstalling the package or image does not automatically delete persisted settings, secrets, or conversation history. Those live in the persistence directory you used, such as `~/.openhands`. ## Get Help From b74c7c40fb65a382295d7975fd056b1e317cdd41 Mon Sep 17 00:00:00 2001 From: Devin Date: Thu, 9 Jul 2026 17:16:47 -0400 Subject: [PATCH 4/6] Update openhands/usage/agent-canvas/setup.mdx Co-authored-by: Engel Nyst --- openhands/usage/agent-canvas/setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openhands/usage/agent-canvas/setup.mdx b/openhands/usage/agent-canvas/setup.mdx index 151b989c..0ca10b28 100644 --- a/openhands/usage/agent-canvas/setup.mdx +++ b/openhands/usage/agent-canvas/setup.mdx @@ -154,7 +154,7 @@ After startup: 1. Open `http://localhost:8000`. 2. Confirm the default local backend shows as connected. -3. Open `Settings > LLM` and configure a model access path. +3. Open `Settings > LLM` and configure a model. 4. Choose `Open Workspace` before starting a conversation if you want the agent to work in a specific folder. 5. Return to the home screen and start a conversation. From b123ec4cb470a4070ca57cac22339135956af4f3 Mon Sep 17 00:00:00 2001 From: Devin Date: Thu, 9 Jul 2026 17:17:29 -0400 Subject: [PATCH 5/6] Update openhands/usage/agent-canvas/overview.mdx Co-authored-by: Engel Nyst --- openhands/usage/agent-canvas/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openhands/usage/agent-canvas/overview.mdx b/openhands/usage/agent-canvas/overview.mdx index 45cadfdf..ebddf856 100644 --- a/openhands/usage/agent-canvas/overview.mdx +++ b/openhands/usage/agent-canvas/overview.mdx @@ -41,7 +41,7 @@ Before installing, decide where you want the agent to run and what files it shou | Setup | Trust Boundary | Best For | |-------|----------------|----------| -| **npm local install** | Runs directly on your machine. The agent server can operate in local workspaces you open. | Fastest local setup when you trust the machine and understand the file access. | +| **npm local install** | Runs directly on your machine. The agent server can operate on the local filesystem. | Fastest local setup when you trust the machine and understand the file access. | | **Docker** | Runs inside a container and only sees the directories you mount. | Local sandboxing and clearer file boundaries. | | **VM or dedicated machine** | Runs on the remote host you control. | Always-on agents, heavier compute, team-shared backends, or personal/work separation. | | **OpenHands Cloud** | Runs in managed OpenHands Cloud sandboxes. | Cloud execution without maintaining your own machine or VM backend. | From a87a8e7bc46aa67613360050a5108bc4d5fd4b95 Mon Sep 17 00:00:00 2001 From: Devin Date: Thu, 9 Jul 2026 17:17:54 -0400 Subject: [PATCH 6/6] Update openhands/usage/agent-canvas/overview.mdx Co-authored-by: Engel Nyst --- openhands/usage/agent-canvas/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openhands/usage/agent-canvas/overview.mdx b/openhands/usage/agent-canvas/overview.mdx index ebddf856..efba3359 100644 --- a/openhands/usage/agent-canvas/overview.mdx +++ b/openhands/usage/agent-canvas/overview.mdx @@ -76,7 +76,7 @@ For the normal local setup, you need: - Node.js 22.12 or later - `npm` -- A model access path, such as a provider API key, OpenHands Cloud key, ACP subscription login, or local model server +- A model access path, such as a provider API key, OpenHands Cloud LLM key, ACP subscription login, or local model server - A folder, repository, or project workspace for the agent to work in For a sandboxed local setup, use Docker instead of the direct npm backend path.