Use Docker with Agent Canvas

Run Agent Canvas with Docker for a sandboxed backend and mounted project workspace.

Use Docker when you want the Agent Canvas distribution and its backend services to run in a container rather than directly on your host. The official image packages the Canvas client, Agent Server, Automation Server, and ingress in one container. Agent Server and its tools can access only the project directories and other resources you expose to the container.

Prerequisites

• Docker installed and running (Docker Desktop on macOS/Windows, or Docker Engine on Linux)
• Agent Canvas installed locally (if connecting from another instance) — see Setup

Run the Official Image

Mount a persistence directory for settings, secrets, and conversation history, and a projects directory for workspace access.

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

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

Agent Canvas is now available at http://localhost:8000/canvas. The backend base URL remains http://localhost:8000, and the agent can access any project under the mounted /projects path.

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.

The agent server can execute arbitrary shell commands inside the container. If exposing it beyond localhost, set LOCAL_BACKEND_API_KEY to a strong secret.

Connect from the Frontend

Start the frontend separately and point it at the container:

agent-canvas --frontend-only

Then add the Docker backend:

1. Click the backend switcher → Manage Backends → Add Backend.
2. Fill in:
   • Name — e.g. docker-backend
   • Host / Base URL — http://localhost:8000
   • API Key — the LOCAL_BACKEND_API_KEY value (check container logs if auto-generated)
3. Save and select it as the active backend.

Related Guides

• Connect and Manage Backends
• Local Backend
• VM / Self-Hosted Installation
• Kubernetes (Helm)