> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-docs-686-repository-boundaries.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Docker with Agent Canvas

> Run Agent Canvas with Docker for a sandboxed backend and mounted project workspace.

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](https://docs.docker.com/get-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](/openhands/usage/agent-canvas/setup)

## Run the Official Image

Mount a persistence directory for settings, secrets, and conversation history, and a projects directory for workspace access.

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    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
    ```

    <Note>
      Docker Desktop for Windows must be installed and running. PowerShell uses backticks (`` ` ``) for line continuation instead of backslashes.
    </Note>
  </Tab>
</Tabs>

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 server. Auto-generated and persisted if not set.                    |
| `OH_SECRET_KEY`         | Secret used to protect stored settings and secrets.                                 |

<Warning>
  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.
</Warning>

## Connect from the Frontend

Start the frontend separately and point it at the container:

```bash theme={null}
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.

## Related Guides

* [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
* [Local Backend](/openhands/usage/agent-canvas/backend-setup/local)
* [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm)
* [Kubernetes (Helm)](/openhands/usage/agent-canvas/backend-setup/kubernetes)