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

# Docker Backend

> Run Agent Canvas in a Docker container as a sandboxed backend.

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](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 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`:

| 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)