Install - OpenHands Docs

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 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
Docker
npx

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.

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

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.

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/agent-canvas.git
cd agent-canvas
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.

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

npx
npm
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

npx
npm
Docker

Stop Agent Canvas, then run the latest package:

npx @openhands/agent-canvas@latest

Stop Agent Canvas, then reinstall the latest package:

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

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.

Uninstall Agent Canvas

npx
npm
Docker

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

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.

​Choose An Install Method

​Verify Prerequisites

​Install And Run

​Confirm It Started

​Common Startup Options

​Environment Variables

​Stop Agent Canvas

​Update Agent Canvas

​Uninstall Agent Canvas

​Next Steps

Choose An Install Method

Verify Prerequisites

Install And Run

Confirm It Started

Common Startup Options

Environment Variables

Stop Agent Canvas

Update Agent Canvas

Uninstall Agent Canvas

Next Steps