Install Agent Canvas

Install, run, update, or uninstall Agent Canvas.

Agent Canvas can run directly on your machine or inside Docker. Use the local npm or npx paths for a direct local backend, or Docker for a sandboxed backend with explicit project mounts. Start with the simplest setup that matches the trust boundary you want.

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.

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.
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 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

npm

Install Node.js 22.12 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.

Docker

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.

npx

Install Node.js 22.12 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

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.

Docker

Create host directories for persistent settings and project files, then start the container.

macOS / Linux:

mkdir -p ~/projects ~/.openhands

docker run -it --rm \
  -p 8000:8000 \
  -v ~/.openhands:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

Windows (PowerShell):

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

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

Agent Canvas starts on http://localhost:8000. The agent can access project files under the mounted /projects directory.

PowerShell uses backticks (`) for line continuation. If Docker reports that it cannot connect to the daemon, start Docker Desktop and run the command again.

npx

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.

From Source

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:

1. Open http://localhost:8000.
2. Confirm the default local backend shows as connected.
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.

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

agent-canvas

npx

npx @openhands/agent-canvas

Docker

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.
-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.
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 <host>:<PORT>.

Stop Agent Canvas

npm

Return to the terminal running Agent Canvas and press Ctrl+C.

npx

Return to the terminal running Agent Canvas and press Ctrl+C.

Docker

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

Stop Agent Canvas, then reinstall the latest package:

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

npx

Stop Agent Canvas, then run the latest package:

npx @openhands/agent-canvas@latest

Docker

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 when you use the documented ~/.openhands mount.

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

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.

npx

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

Docker

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

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.

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.

Please join the OpenHands Slack community to share feedback and open an issue for problems you find while testing the preview.

Install and Run

Download the installer for your operating system from the OpenHands releases page.

macOS (Apple silicon)

1. Download the Agent-Canvas-<version>-arm64.dmg file.
2. Open the disk image and drag Agent Canvas to Applications.
3. Launch Agent Canvas from Applications.

Pre-built desktop releases support Apple silicon Macs. On an Intel Mac, use the npm or from-source installation method.

Windows

1. Download the Agent-Canvas-Setup-<version>.exe installer.
2. Run the installer. If Windows SmartScreen prompts you, confirm that you want to continue.
3. Launch Agent Canvas from the Start 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

On macOS, the app is ad-hoc signed. If macOS reports that Agent Canvas is damaged or cannot be opened, clear its quarantine attribute in Terminal, then launch it again:

xattr -d com.apple.quarantine /Applications/Agent\ Canvas.app

Do not use xattr -cr; that command does not clear this issue on macOS Sequoia.

To stop the app, quit Agent Canvas from its application menu or window controls. 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 or uninstall it from Installed apps on Windows.

Next Steps

• First Time Setup
• Connect and Manage Backends
• Manage LLM Profiles
• Use Docker with Agent Canvas
• Troubleshooting