Skip to content

πŸ™Œ OpenHands: AI-Driven Development

docs: multiple docker sandboxes (#17769)

Engel Nystda8f701e0e8e
diff --git a/README.md b/README.md
index d0759960a6..6c7c06a268 100644
--- a/README.md
+++ b/README.md
@@ -104,7 +104,24 @@ docker run -it --rm \
The agent will be able to access any project under `PROJECTS_PATH`.
-### Option 3: From Source
+### Option 3: With Multiple Docker Sandboxes
+
+Run each new conversation in its own Docker container, with its own Agent Server and tools. This is useful for running several agents concurrently. Canvas and the outer Agent Server run on your host and route conversation requests to the containers.
+
+**Prerequisites**: Node.js 24 or later, `uv`, and a running Docker Desktop (macOS) or Docker Engine/Desktop (Linux). The user starting Canvas must be able to run `docker` commands.
+
+**macOS / Linux:**
+
+```sh
+npm install -g @openhands/agent-canvas
+OH_CONVERSATION_RUNTIME=docker agent-canvas
+```
+
+Open [http://localhost:8000](http://localhost:8000) and start a new conversation. Existing local conversations are not converted. Each container mounts its conversation's workspace and persisted state, so workspace files and conversation history survive container replacement. Conversations using the same host workspace still share those files; choose separate directories or worktrees to avoid conflicting edits.
+
+This setting isolates conversation execution; it does not move the entire Canvas or automation service into a sandbox. For Windows, see [README.windows.md](./README.windows.md#option-3-with-multiple-docker-sandboxes-wsl-2).
+
+### Option 4: From Source
> [!WARNING]
> This runs the agent-server directly on the machine you're installing on β€” the agent will have full access to your filesystem!
diff --git a/README.windows.md b/README.windows.md
index 23a4c76a0a..a2267adbc2 100644
--- a/README.windows.md
+++ b/README.windows.md
@@ -30,3 +30,9 @@ Open [http://localhost:8000/canvas](http://localhost:8000/canvas) in your browse
The agent will be able to access any project under `PROJECTS_PATH`.
The quickstart restricts the published port to host loopback before explicitly enabling session-key injection. If you publish the port on a LAN or public interface, omit `AGENT_CANVAS_ALLOW_LAN_SESSION_KEY`, set `LOCAL_BACKEND_API_KEY` to a strong value, and enter that value in the UI.
+
+## Option 3: With Multiple Docker Sandboxes (WSL 2)
+
+For per-conversation containers, run Canvas inside a Linux distribution under WSL 2, with Docker Desktop's WSL integration enabled for that distribution. Install Node.js 24 or later and `uv` inside WSL, and confirm that `docker info` succeeds there.
+
+Run the [multiple-sandbox quickstart](./README.md#option-3-with-multiple-docker-sandboxes) in the WSL shell, using workspace paths inside that Linux environment. The native Windows host is not supported by this runtime, which uses POSIX user/group IDs.