Docker Backend

Run Agent Canvas in a Docker container as a sandboxed backend.

The official Docker image packages the full Agent Canvas stack — backend and frontend — in a single container. The agent runs inside the container rather than directly on your host, giving you a sandboxed environment out of the box.

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 running at http://localhost:8000. 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 Backend
• VM / Self-Hosted Backend