GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing docs.openhands.dev — Install Agent Canvas - OpenHands Docs

Quick Start

Install Agent Canvas with npm and start the full local stack:

npm install -g @openhands/agent-canvas
agent-canvas

Agent Canvas starts on http://localhost:8000; open that URL manually if your browser does not. Then follow First Time Setup to configure a model and open a workspace. If installation or startup fails, see Verify Prerequisites. If you would rather not install npm packages, prefer an installer with bundled Node.js and uv, or want a sandboxed setup, see More Install Options below.

Treat agents and ACP processes as untrusted: they can run shell commands and read or write files with your user account’s permissions. Agent Canvas is the client and does not isolate them — use a container, sandbox, or VM for a tighter boundary, and review VM / Self-Hosted Installation before exposing backend services to a network you do not control.

More Install Options

The agent-canvas launcher runs 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.

Method	Use It When	What The Agent Can Access
Desktop app (preview)	You want an installer with bundled Node.js and `uv`. Go to macOS, Windows, or Linux instructions.	The default local backend runs directly on your machine and can work in local workspaces you open.
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.

For an installer, choose the desktop preview below. For a browser setup, use npx for a quick first run or npm for a reusable agent-canvas command. Use Docker when you specifically want sandboxing.

Desktop App (Preview Build)

The desktop app is an early preview for user testing. It bundles Node.js and uv, starts its local backend automatically, and does not require you to install npm packages, clone the source, or keep a terminal open. Skip the command-line prerequisites and installation sections below.

Preview builds may have rough edges. The macOS app is not yet signed with an Apple Developer ID or notarized, so Gatekeeper may block it; see desktop troubleshooting. Windows may show a SmartScreen prompt. Current installers support Apple silicon and Intel Macs, and x64 Windows and Linux.

Download the file for your operating system from the Assets list on the latest OpenHands release. Replace <version> in the filenames below with the release version. Older builds are on the releases page.

macOS

Download OpenHands-Agent-Canvas-<version>-universal.dmg from the latest release assets.
Open the disk image and drag OpenHands Agent Canvas to Applications.
Launch OpenHands Agent Canvas from Applications.

The universal disk image includes Node.js and uv for both Apple silicon and Intel Macs.

Windows

Download OpenHands-Agent-Canvas-Setup-<version>.exe from the latest release assets.
Run the installer. If Windows SmartScreen prompts you, confirm that the installer came from the official OpenHands release before continuing.
Launch OpenHands Agent Canvas from the Start menu.

Linux

Choose a package from the latest release assets:

AppImage: Download OpenHands.Agent.Canvas-<version>.AppImage, make it executable in your file manager’s permissions or with chmod +x, then run the file.
Debian / Ubuntu: Download agent-canvas_<version>_amd64.deb, install it with your package manager (for example, sudo apt install ./agent-canvas_<version>_amd64.deb), then launch OpenHands Agent Canvas from your applications menu.

First Launch

During startup, select Show details to view and copy the live startup log if startup takes longer than expected or fails. Once the app opens, follow First Time Setup to configure a model and open a workspace. The desktop app can also run conversations in DigitalOcean sandboxes. See DigitalOcean Managed Agents.

Troubleshooting and Lifecycle

If macOS reports that the app is damaged or cannot be opened, first confirm that you downloaded it from the official OpenHands release. After moving it to Applications, clear its quarantine attribute in Terminal, then launch it again:

xattr -dr com.apple.quarantine "/Applications/OpenHands Agent Canvas.app"

To stop the app, quit OpenHands Agent Canvas from its application menu. To run it again, launch the installed app. To update it, download and install the latest desktop release; Settings > Application also shows the installed version and can check for updates. To uninstall, quit the app and move it to the Trash on macOS, uninstall it from Installed apps on Windows, or remove the AppImage or Debian package on Linux. Please join the OpenHands Slack community to share preview feedback and open an issue for problems you find.

Verify Prerequisites

These prerequisites apply to the npm, npx, and Docker methods. Desktop installer users can go directly to First Time Setup.

npm
Docker
npx

Install Node.js 24 or later and uv, then verify both tools are available:

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.

Install Docker and make sure the Docker daemon is running:

docker --version
docker ps

On macOS and Windows, open Docker Desktop before running the container.

Install Node.js 24 or later and uv, then verify the tools are available:

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.

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.

Install And Run

npm
Docker
npx
From Source

Install the published package globally:

npm install -g @openhands/agent-canvas

Start the full local stack:

agent-canvas

Agent Canvas starts on http://localhost:8000 by default. If your browser does not open automatically, open that URL manually.

Use a named Docker volume for persistent settings and a host directory for project files, then start the container.macOS / Linux:

mkdir -p ~/projects

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -v openhands-data:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\projects" | Out-Null

docker run -it --rm `
  -p 127.0.0.1:8000:8000 `
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true `
  -v openhands-data:/home/openhands/.openhands `
  -v "$($env:USERPROFILE)\projects:/projects" `
  ghcr.io/openhands/agent-canvas:latest

The Docker image serves Agent Canvas at http://localhost:8000/canvas. The agent can access project files under the mounted /projects directory. The 127.0.0.1: prefix publishes the port on your machine only, so other devices on your network cannot reach the agent server.Docker listens on all interfaces inside the container so port publishing works. By default, that prevents Agent Canvas from embedding its session API key in the page, and the browser asks you to enter the key. The commands above explicitly opt in with AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true while keeping the published host port on localhost. On first connection, the UI receives the key automatically; you do not need a model-provider key to connect to the backend.

Anyone who can reach the frontend can obtain an embedded session key and access the backend. Keep this opt-in paired with -p 127.0.0.1:8000:8000. If you publish on a LAN or public interface, or expose the UI through a proxy or tunnel, omit AGENT_CANVAS_ALLOW_LAN_SESSION_KEY and enter the backend key manually. For internet-facing deployments, follow VM / Self-Hosted Installation.

Docker creates openhands-data on first use and keeps it after the container exits, including with --rm. Reuse the same volume on subsequent runs. The image places new default conversation workspaces under /home/openhands/.openhands/agent-canvas/workspaces in this volume, so they survive container recreation with the same volume. The /projects bind mount remains separate; the volume does not copy older workspaces or host project directories into it.The example uses --rm, which does not enable automatic recovery. If you need Docker to restart the container when Agent Server stops responding, run it with a restart policy such as --restart unless-stopped instead of --rm. Agent Canvas exits with a failure status when Agent Server stops responding, allowing that policy to restart it.

On Linux, binding ~/.openhands can cause unable to open database file: the container user defaults to UID 10001, while the host directory is usually owned by your own user, such as UID 1000. A named volume avoids this ownership mismatch. Switching to a new volume does not copy existing settings from ~/.openhands.

If startup reports an unwritable state directory or bind mount, check that the container user (UID 10001 by default) can write to the mounted paths. On SELinux hosts, check the bind mount’s labeling as well. An intentionally read-only workspace is allowed with a warning.To move existing settings from ~/.openhands into the volume, run this once before starting Agent Canvas:

docker run --rm -u 0 --entrypoint sh \
  -v ~/.openhands:/from:ro \
  -v openhands-data:/to \
  ghcr.io/openhands/agent-canvas:latest \
  -c 'cp -a /from/. /to/ && chown -R 10001:10001 /to'

To use DigitalOcean sandboxes, follow the DigitalOcean Docker setup to enable the integration and configure authentication.

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:

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:

git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm install
npm run dev

For development-specific environment variables and commands, see Contribute / Development.

Confirm It Started

After startup:

Open http://localhost:8000.
Confirm the default local backend shows as connected.
Open Settings > LLM and configure a model.
Choose Open Workspace before starting a conversation if you want the agent to work in a specific folder.
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.

Run Agent Canvas Again

After you close the terminal or restart your computer, start Agent Canvas with the same command you used to install it. Keep that terminal or Docker container running while you use the browser UI.

npm
npx
Docker

agent-canvas

npx @openhands/agent-canvas

Run the same docker run command from Install and Run. The browser connects to the host port you map, while the backend and model configuration run where the Agent Canvas process or container is running.

If the UI opens but the backend is disconnected or a model cannot respond, use Troubleshooting to identify the affected part of the stack.

Common Startup Options

Option	Description
`-p`, `--port <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.
`--verbose`	Run the backends with `DEBUG` logging. Without it, they start at `WARNING`.
`-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:

agent-canvas --port 3000

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.
`AGENT_CANVAS_ALLOW_LAN_SESSION_KEY`	Docker quickstart opt-in to embed the session key in the frontend. Use `true` only with the host port restricted to localhost; omit it for LAN/public access.
`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`.
`AUTOMATION_KV_SECRET`	Secret used to protect automation key-value storage. When it is not set, the launcher pins the first session key to `automation-kv-secret.txt` and reuses it, so rotating `SESSION_API_KEY` does not make existing automation KV data unreadable. The pin file must be a regular file with private permissions; otherwise the launcher fails closed.
`LOG_LEVEL`	Log level for the agent server. Overrides the `WARNING` default; Uvicorn’s `--log-level` follows it.
`AUTOMATION_LOG_LEVEL`	Log level for the automation service. Overrides the `WARNING` default.
`PORT`	Ingress port inside the Docker container. Map it with `-p <host>:<PORT>`.

Session Keys And The API-Key Prompt

Agent Canvas uses different credentials for connecting to a backend and accessing a model:

Key	What It Does	Where To Configure It
Session/backend API key	Authenticates the browser to your Agent Canvas backend. It is generated locally or supplied by the backend operator.	Enter it at the initial API-key prompt or in the backend connection settings.
Model-provider API key	Authenticates model requests to your chosen provider, such as Anthropic, OpenAI, or OpenHands Cloud.	Configure it during First Time Setup or in `Settings > LLM`.

A model-provider key will not unlock a local backend. OH_SECRET_KEY is a separate encryption secret for stored settings; do not enter it at the API-key prompt.

Recover When Docker Asks For A Key

The prompt is expected when automatic session-key delivery is disabled. You can authenticate without recreating your settings volume:

In another terminal, run docker ps and find the Agent Canvas container’s ID or name.
If you started it with LOCAL_BACKEND_API_KEY, use that value. Otherwise, retrieve the generated key with the following command, replacing CONTAINER with the ID or name. This works in macOS/Linux shells and PowerShell for the default Docker configuration:
docker exec CONTAINER cat /home/openhands/.openhands/agent-canvas/api-key.txt
Keep the printed key private. The generated key lives in the openhands-data volume and is reused when you restart with that volume. If you customized the state directory, use the api-key.txt path that the container logs when it first generates the key.
Open http://localhost:8000/canvas, enter the backend key, and confirm the backend connects. Then configure your model separately in Settings > LLM.

For automatic connection on your own machine, stop the container and rerun the localhost-only Docker command above with the opt-in and the same volume. If the browser retained an old key after you changed the backend key or switched volumes, update the key in the backend connection settings, or open a private browser window and enter the current key.

Configure Your Own Docker Backend Key

To supply a key instead of using the generated one, set LOCAL_BACKEND_API_KEY in your host environment to a strong, unique secret, then add -e LOCAL_BACKEND_API_KEY to docker run. Docker passes the environment value into the container. Supply the same value on subsequent runs; an explicitly configured key takes precedence over the generated key file and does not replace that file. When automatic key delivery is disabled, users must enter this value in the UI. Do not enable automatic delivery to bypass authentication on a shared or public deployment.

Stop Agent Canvas

npm
npx
Docker

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:

docker ps
docker stop <container-id-or-name>

Update Agent Canvas

npm
npx
Docker

Stop Agent Canvas, then reinstall the latest package:

npm install -g @openhands/agent-canvas@latest
agent-canvas --version

Stop Agent Canvas, then run the latest package:

npx @openhands/agent-canvas@latest

Stop the running container, pull the latest image, then run the container again:

docker pull ghcr.io/openhands/agent-canvas:latest

Your settings and conversation data are stored outside the package or image: in ~/.openhands for npm and npx, and in the openhands-data volume for Docker. Pulling a new image does not change the volume.

Recover or reset: Use Troubleshooting when the browser is blank, a port is busy, the backend is unreachable, a model or API key fails, or an update or uninstall is stuck. It also explains clean removal and reinstall.

Uninstall Agent Canvas

npm
npx
Docker

Stop any running Agent Canvas process, then uninstall the package:

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.

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:

npm cache verify

Stop any running container, then remove the image if you no longer need it:

docker ps
docker stop <container-id-or-name>
docker rmi ghcr.io/openhands/agent-canvas:latest

To also delete settings, secrets, and conversation history, remove the settings volume:

docker volume rm openhands-data

Uninstalling the package or image does not automatically remove your persisted data. To delete local settings, secrets, and conversation history, remove ~/.openhands for npm and npx, or the openhands-data volume for Docker. If you bound ~/.openhands in an older Docker setup, remove that directory too.

Next Steps

First Time Setup

Choose your agent, connect a backend, and add a model.

Connect and Manage Backends

Add, switch, and remove the backends Canvas connects to.

Manage LLM Profiles

Save model configurations and switch between them in conversations.

Troubleshooting

Fix install, startup, backend, and model issues.

Was this page helpful?

You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

GeezerVison

​Quick Start

​More Install Options

​Desktop App (Preview Build)

​macOS

​Windows

​Linux

​First Launch

​Troubleshooting and Lifecycle

​Verify Prerequisites

​Install And Run

​Confirm It Started

​Run Agent Canvas Again

​Common Startup Options

​Environment Variables

​Session Keys And The API-Key Prompt

​Recover When Docker Asks For A Key

​Configure Your Own Docker Backend Key

​Stop Agent Canvas

​Update Agent Canvas

​Uninstall Agent Canvas

​Next Steps