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)
Docker Desktop for Windows must be installed and running. PowerShell uses backticks (`) for line continuation instead of backslashes.
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.
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.
