Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 31 additions & 10 deletions openhands/usage/agent-canvas/backend-setup/docker.mdx
Original file line number Diff line number Diff line change
@@ -1,26 +1,47 @@
---
title: Docker Backend
description: Run Agent Canvas in a Docker container as a sandboxed backend.

Check warning on line 3 in openhands/usage/agent-canvas/backend-setup/docker.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

openhands/usage/agent-canvas/backend-setup/docker.mdx#L3

Did you really mean 'sandboxed'?
---

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.

Check warning on line 6 in openhands/usage/agent-canvas/backend-setup/docker.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

openhands/usage/agent-canvas/backend-setup/docker.mdx#L6

Did you really mean 'sandboxed'?

## Prerequisites

- [Docker](https://docs.docker.com/get-docker/) installed and running
- [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:

```bash
docker run -it --rm \
-p 8000:8000 \
-v ~/.openhands:/home/openhands/.openhands \
-v ~/projects:/projects \
ghcr.io/openhands/agent-canvas:latest
```
Mount a persistence directory for settings, secrets, and conversation history, and a projects directory for workspace access.

<Tabs>
<Tab title="macOS / Linux">
```bash
mkdir -p ~/projects ~/.openhands

Check warning on line 20 in openhands/usage/agent-canvas/backend-setup/docker.mdx

View check run for this annotation

Mintlify / Mintlify Validation (allhandsai) - vale-spellcheck

openhands/usage/agent-canvas/backend-setup/docker.mdx#L20

Did you really mean 'mkdir'?

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

Expand Down
24 changes: 22 additions & 2 deletions openhands/usage/agent-canvas/setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,18 +44,38 @@ description: Install and run Agent Canvas via npm or Docker.
| `OH_AGENT_SERVER_VERSION` | Pin a specific agent server version (e.g. `0.1.0`) |
</Tab>
<Tab title="Docker">
**Prerequisites:** [Docker](https://docs.docker.com/get-docker/).
**Prerequisites:** [Docker](https://docs.docker.com/get-docker/) (Docker Desktop on macOS/Windows, or Docker Engine on Linux).

A Docker image is available that sandboxes the entire Agent Canvas stack. Mount your project files and a persistence directory for settings, secrets, and conversation history:
A Docker image is available that sandboxes the entire Agent Canvas stack. Mount your project files and a persistence directory for settings, secrets, and conversation history.

Create a host directory for your projects (the agent can access any folder under this path) and run the container:

**macOS / Linux:**
```bash
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
```

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

### Environment Variables

Configuration is passed via `-e` flags on `docker run`:
Expand Down
Loading