Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt

Use this file to discover all available pages before exploring further.

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
  • 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: 
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 server. Auto-generated and persisted if not set.
OH_SECRET_KEYSecret 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.