Install

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 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/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:

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.

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

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

npm

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

npx

Stop Agent Canvas, then run the latest package:

npx @openhands/agent-canvas@latest

npm

Stop Agent Canvas, then reinstall the latest package:

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

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.

Uninstall Agent Canvas

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

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.

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.

Next Steps

• First Time Setup
• Connect and Manage Backends
• LLM Profiles and Model Configuration
• Docker Backend
• Troubleshooting