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.
AGENT_CANVAS_DISABLE_TELEMETRY	Set to 1 or true to disable Agent Canvas product telemetry.

You can also pass --disable-telemetry to the Agent Canvas runtime. Use the environment variable for deployment configuration because older images ignore an unknown environment variable but reject an unknown runtime flag.

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.

Let the Agent Use Docker

By default the agent cannot run containers: docker is installed in the image, but the daemon cannot start inside an unprivileged container. If the agent tries, it fails with error creating default "bridge" network: operation not permitted.

That matters for tasks where a container is part of the workflow — building a Dockerfile and running it to confirm the change works, bringing up a docker compose stack to reproduce a bug, or using a toolchain that is only published as an image. Without a daemon the agent can edit those files but cannot verify them.

To enable it, start the container with --privileged:

docker run -it --rm \
  --privileged \
  -p 8000:8000 \
  -v ~/.openhands:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

--privileged gives the container broad access to the host kernel, which substantially weakens the isolation between the agent and your machine. The agent can execute arbitrary shell commands, so grant this only on a host you are willing to expose and only when the agent genuinely needs to run containers.

Verify from inside the container:

docker exec -it <container> docker info

There is no safer middle ground. The Docker daemon needs kernel capabilities that are granted by the host when the container starts, so they cannot be acquired later — and rootless Docker does not avoid this: the daemon starts, but containers it creates fail to launch (error mounting "proc" to rootfs: operation not permitted).

OpenHands Enterprise solves this differently, running each sandbox under a hardened runtime that provides kernel-level isolation so nested containers run unprivileged. See Running Docker in the Agent Sandbox.

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)
• Running Docker in the Agent Sandbox — how Enterprise does this without --privileged