Use Docker with Agent Canvas

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
Windows (PowerShell)

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

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 Agent Canvas backend API. If not set, a key is generated and saved to `~/.openhands/agent-canvas/api-key.txt` in the mounted persistence directory.
`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.
`LMNR_PROJECT_API_KEY`	Enables SDK tracing to Laminar. See Enable SDK Tracing.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Enables SDK trace export to an OTLP-compatible backend such as Jaeger, Grafana Tempo, Honeycomb, Datadog, or New Relic.
`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`	OTLP transport protocol, usually `http/protobuf` or `grpc`.
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	Optional authentication headers for your OTLP backend.

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. Product telemetry is separate from the SDK tracing variables above, which send traces only to a backend you configure.

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.

Enable SDK Tracing

The container runs the OpenHands Agent Server, which uses the OpenHands SDK. The SDK emits traces automatically when Laminar or OpenTelemetry environment variables are set, so pass them to docker run to trace Agent Canvas conversations. For the full variable reference, see Observability & Tracing.

Laminar example

mkdir -p ~/projects ~/.openhands

docker run -it --rm \
  -p 8000:8000 \
  -e LMNR_PROJECT_API_KEY="your-laminar-api-key" \
  -v ~/.openhands:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

OTLP collector example

If your collector runs on the host, localhost inside the container refers to the container itself. Use host.docker.internal; on Linux, also add the host gateway alias as shown:

mkdir -p ~/projects ~/.openhands

docker run -it --rm \
  --add-host=host.docker.internal:host-gateway \
  -p 8000:8000 \
  -e OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://host.docker.internal:4317" \
  -e OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="grpc" \
  -v ~/.openhands:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

If the collector runs in another container, put both containers on the same Docker network and use the collector’s container or Compose service name in the endpoint, for example http://jaeger:4317.

Exporters do not backfill earlier conversations. Configure tracing before starting the conversations you want to observe.

What the Image Provides

The image includes SDK trace instrumentation and export. It does not include a trace backend: Laminar, Jaeger, Grafana Tempo, Datadog, Honeycomb, and New Relic are services you run or subscribe to separately. It also does not expose a Prometheus /metrics endpoint. The SDK exporter sends traces, not scrape metrics. To view traces in Grafana, export them to Grafana Tempo or another trace backend and add that backend as a Grafana data source. The SDK’s token, cost, and latency tracking is a separate feature for SDK integrations; see Metrics Tracking.

Inspect Conversations Through the Backend API

The backend API is separate from tracing and uses the same LOCAL_BACKEND_API_KEY as the UI. You can use it to inspect conversations stored in the Docker backend, including one that does not appear in the left panel.

# Use the value you passed as LOCAL_BACKEND_API_KEY, or the generated key.
export LOCAL_BACKEND_API_KEY="$(cat ~/.openhands/agent-canvas/api-key.txt)"

curl -sS \
  -H "X-Session-API-Key: $LOCAL_BACKEND_API_KEY" \
  http://localhost:8000/api/conversations/search

After you find a conversation ID, list its most recent events:

export CONVERSATION_ID="conversation-id"

curl -sS \
  -H "X-Session-API-Key: $LOCAL_BACKEND_API_KEY" \
  "http://localhost:8000/api/conversations/$CONVERSATION_ID/events/search?limit=20&sort_order=TIMESTAMP_DESC"

Connect from the Frontend

Start the frontend separately and point it at the container:

agent-canvas --frontend-only

Then add the Docker backend:

Click the backend switcher → Manage Backends → Add Backend.
Fill in:
- Name — e.g. docker-backend
- Host / Base URL — http://localhost:8000
- API Key — the LOCAL_BACKEND_API_KEY value, or the generated key in ~/.openhands/agent-canvas/api-key.txt
Save and select it as the active backend.

Connect and Manage Backends
Local Backend
VM / Self-Hosted Installation
Kubernetes (Helm)
Running Docker in the Agent Sandbox — how Enterprise does this without --privileged

Install Canvas

Automations

Use Canvas

Connect Backends

Self-Host Backend Services

Contribute And Troubleshoot

Release Notes

Use Docker with Agent Canvas

Prerequisites

Run the Official Image

Environment Variables

Let the Agent Use Docker

Enable SDK Tracing

Laminar example

OTLP collector example

What the Image Provides

Inspect Conversations Through the Backend API

Connect from the Frontend

​Prerequisites

​Run the Official Image

​Environment Variables

​Let the Agent Use Docker

​Enable SDK Tracing

​Laminar example

​OTLP collector example

​What the Image Provides

​Inspect Conversations Through the Backend API

​Connect from the Frontend

​Related Guides

Prerequisites

Run the Official Image

Environment Variables

Let the Agent Use Docker

Enable SDK Tracing

Laminar example

OTLP collector example

What the Image Provides

Inspect Conversations Through the Backend API

Connect from the Frontend

Related Guides