Use Docker when you want Agent Canvas and its agent tools to run in a container rather than directly on your host. The official image packages the full Agent Canvas stack — backend and frontend — in a single container, with access only to the project directories you mount.
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)
Docker Desktop for Windows must be installed and running. PowerShell uses backticks (`) for line continuation instead of backslashes.
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:
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:
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 (check container logs if auto-generated)
- Save and select it as the active backend.
