Skip to main content
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.
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:
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:
--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:
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:
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.