Skip to main content
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. 
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
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:
VariablePurpose
PORTIngress port inside the container (default 8000). Map it with -p <host>:<PORT>.
LOCAL_BACKEND_API_KEYAPI key for the Agent Canvas backend API. Auto-generated and persisted if not set.
OH_SECRET_KEYSecret used to protect stored settings and secrets.
LMNR_PROJECT_API_KEYEnables built-in SDK tracing to Laminar.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTEnables built-in SDK trace export to an OTLP-compatible backend such as Jaeger, Honeycomb, Datadog, New Relic, or Grafana Tempo.
OTEL_EXPORTER_OTLP_TRACES_PROTOCOLOTLP transport protocol, usually http/protobuf or grpc.
OTEL_EXPORTER_OTLP_TRACES_HEADERSOptional authentication headers for your OTLP backend.
For the full tracing reference, see Observability & Tracing.
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.

​
View Backend Conversations and Events

Agent Canvas includes a backend API for conversations and events. This is built in and uses the same LOCAL_BACKEND_API_KEY that the UI uses. It is separate from observability tracing. Use this API if you need to inspect conversations stored in the Docker backend, including a conversation that is not visible in the left panel. 
# Use the value you passed as LOCAL_BACKEND_API_KEY.
# If you did not set one, check the container logs for the generated key.
export LOCAL_BACKEND_API_KEY="your-backend-api-key"

curl -sS \
  -H "X-Session-API-Key: $LOCAL_BACKEND_API_KEY" \
  http://localhost:8000/api/conversations/search
After you find a conversation ID, inspect 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"
Observability exporters do not backfill old conversations. Set up tracing before starting the conversations you want to observe.

​
Built-in Tracing vs. External Backends

Built into Agent Canvas Docker:
  • The OpenHands Agent Server runs inside the container and uses the OpenHands SDK.
  • The SDK automatically emits traces when Laminar or OTEL environment variables are present.
  • The backend conversation and event APIs are available behind LOCAL_BACKEND_API_KEY.
Not built into Agent Canvas Docker:
  • A Prometheus /metrics endpoint for scraping agent execution metrics.
  • A Grafana connector that authenticates into Agent Canvas or makes conversations appear in the left panel.
  • Hosted Laminar, Jaeger, Tempo, Prometheus, Grafana, Datadog, Honeycomb, or New Relic services. Those are external observability systems you run or subscribe to separately.
The SDK also has built-in token, cost, and latency tracking for SDK-based integrations; see Metrics Tracking. That is different from service metrics scraped by Prometheus. For Grafana, the typical tracing setup is to export OTLP traces from Agent Canvas to Grafana Tempo or another trace backend, then add that backend as a Grafana data source. Prometheus is useful for metrics, but the SDK tracing exporter sends traces, not Prometheus scrape metrics.

​
Enable SDK Tracing

The Docker image starts the OpenHands Agent Server inside the container, and the Agent Server uses the OpenHands SDK. To enable tracing for Agent Canvas conversations, pass Laminar or OpenTelemetry environment variables to docker run.

​
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 your host machine, remember that localhost inside the container means the Agent Canvas container itself. Use host.docker.internal on Docker Desktop, or add the host gateway alias on Linux. 
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.

​
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.