Install

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

npm
Docker

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 Installation.
`--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`)

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:

Confirm the default local backend is healthy.
Open Settings > LLM and configure a provider, model, and API key.
Open Customize if you want to add skills or MCP servers.
Return to the home screen and enter a prompt to start your first conversation.
If you want the conversation tied to a local folder, choose Open Workspace first.

Pre-built Automations

Backends

CLI Flags

Environment Variables

Environment Variables

First Steps After Launch

Next Steps

​CLI Flags

​Environment Variables

​Environment Variables

​First Steps After Launch

​Next Steps

CLI Flags

Environment Variables

Environment Variables

First Steps After Launch

Next Steps