Install

Install and run Agent Canvas via npm or Docker.

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 Backend before exposing it to a network you do not control.

npm

Prerequisites: Node.js 22.12 or later, npm, and uv.

Install:

npm install -g @openhands/agent-canvas

Run:

agent-canvas

By default, Agent Canvas starts on http://localhost:8000.

CLI Flags

Flag	Description
-p, --port <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 Backend.
--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

Environment Variables

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)

Docker

Prerequisites: Docker (Docker Desktop on macOS/Windows, or Docker Engine on Linux).

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.

Create a host directory for your projects (the agent can access any folder under this path) and run 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

On Windows, Docker Desktop must be installed and running. PowerShell uses backticks (`) for line continuation instead of backslashes.

Environment Variables

Configuration is passed via -e flags on docker run:

Variable	Purpose
PORT	Ingress port inside the container (default 8000). Map it with -p <host>:<PORT>.
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

If you want to clone the repository, run custom dev modes, or configure Vite-specific environment variables, use the Contribute / Development guide instead.

First Steps After Launch

After the UI opens:

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.

Next Steps

• Connect and Manage Backends
• LLM Profiles and Model Configuration
• Customize and Settings