From 177ab718a0f610d5b7ce349a6e50dbbdf20d7894 Mon Sep 17 00:00:00 2001 From: Joe LaPenna Date: Mon, 13 Apr 2026 18:19:27 -0700 Subject: [PATCH] docs(gateway): Document Docker-out-of-Docker Paradox and constraint (#65473) * docs: Detail Docker-out-of-Docker paradox and host path requirements * docs: fix spelling inside sandboxing.md * fix: grammar typo as suggested by Greptile --- docs/gateway/sandboxing.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md index 1d6b127957a..aa13fa18451 100644 --- a/docs/gateway/sandboxing.md +++ b/docs/gateway/sandboxing.md @@ -77,6 +77,18 @@ OpenShell-specific config lives under `plugins.entries.openshell.config`. | **Bind mounts** | `docker.binds` | N/A | N/A | | **Best for** | Local dev, full isolation | Offloading to a remote machine | Managed remote sandboxes with optional two-way sync | +### Docker backend + +The Docker backend is the default runtime, executing tools and sandbox browsers locally via the Docker daemon socket (`/var/run/docker.sock`). Sandbox container isolation is determined by Docker namespaces. + +**Docker-out-of-Docker (DooD) Constraints**: +If you deploy the OpenClaw Gateway itself as a Docker container, it orchestrates sibling sandbox containers using the host's Docker socket (DooD). This introduces a specific path mapping constraint: + +- **Config Requires Host Paths**: The `openclaw.json` `workspace` configuration MUST contain the **Host's absolute path** (e.g. `/home/user/.openclaw/workspaces`), not the internal Gateway container path. When OpenClaw asks the Docker daemon to spawn a sandbox, the daemon evaluates paths relative to the Host OS namespace, not the Gateway namespace. +- **FS Bridge Parity (Identical Volume Map)**: The OpenClaw Gateway native process also writes heartbeat and bridge files to the `workspace` directory. Because the Gateway evaluates the exact same string (the host path) from within its own containerized environment, the Gateway deployment MUST include an identical volume map linking the host namespace natively (`-v /home/user/.openclaw:/home/user/.openclaw`). + +If you map paths internally without absolute host parity, OpenClaw natively throws an `EACCES` permission error attempting to write its heartbeat inside the container environment because the fully qualified path string doesn't exist natively. + ### SSH backend Use `backend: "ssh"` when you want OpenClaw to sandbox `exec`, file tools, and media reads on