openclaw-skill/openclaw-knowhow-skill/output/openclaw-docs_data/pages/Sandboxing_6adf0ed8d5.json

{
  "title": "Sandboxing",
  "content": "OpenClaw can run **tools inside Docker containers** to reduce blast radius.\nThis is **optional** and controlled by configuration (`agents.defaults.sandbox` or\n`agents.list[].sandbox`). If sandboxing is off, tools run on the host.\nThe Gateway stays on the host; tool execution runs in an isolated sandbox\nwhen enabled.\n\nThis is not a perfect security boundary, but it materially limits filesystem\nand process access when the model does something dumb.\n\n## What gets sandboxed\n\n* Tool execution (`exec`, `read`, `write`, `edit`, `apply_patch`, `process`, etc.).\n* Optional sandboxed browser (`agents.defaults.sandbox.browser`).\n  * By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it.\n    Configure via `agents.defaults.sandbox.browser.autoStart` and `agents.defaults.sandbox.browser.autoStartTimeoutMs`.\n  * `agents.defaults.sandbox.browser.allowHostControl` lets sandboxed sessions target the host browser explicitly.\n  * Optional allowlists gate `target: \"custom\"`: `allowedControlUrls`, `allowedControlHosts`, `allowedControlPorts`.\n\n* The Gateway process itself.\n* Any tool explicitly allowed to run on the host (e.g. `tools.elevated`).\n  * **Elevated exec runs on the host and bypasses sandboxing.**\n  * If sandboxing is off, `tools.elevated` does not change execution (already on host). See [Elevated Mode](/tools/elevated).\n\n`agents.defaults.sandbox.mode` controls **when** sandboxing is used:\n\n* `\"off\"`: no sandboxing.\n* `\"non-main\"`: sandbox only **non-main** sessions (default if you want normal chats on host).\n* `\"all\"`: every session runs in a sandbox.\n  Note: `\"non-main\"` is based on `session.mainKey` (default `\"main\"`), not agent id.\n  Group/channel sessions use their own keys, so they count as non-main and will be sandboxed.\n\n`agents.defaults.sandbox.scope` controls **how many containers** are created:\n\n* `\"session\"` (default): one container per session.\n* `\"agent\"`: one container per agent.\n* `\"shared\"`: one container shared by all sandboxed sessions.\n\n`agents.defaults.sandbox.workspaceAccess` controls **what the sandbox can see**:\n\n* `\"none\"` (default): tools see a sandbox workspace under `~/.openclaw/sandboxes`.\n* `\"ro\"`: mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`).\n* `\"rw\"`: mounts the agent workspace read/write at `/workspace`.\n\nInbound media is copied into the active sandbox workspace (`media/inbound/*`).\nSkills note: the `read` tool is sandbox-rooted. With `workspaceAccess: \"none\"`,\nOpenClaw mirrors eligible skills into the sandbox workspace (`.../skills`) so\nthey can be read. With `\"rw\"`, workspace skills are readable from\n`/workspace/skills`.\n\n## Custom bind mounts\n\n`agents.defaults.sandbox.docker.binds` mounts additional host directories into the container.\nFormat: `host:container:mode` (e.g., `\"/home/user/source:/source:rw\"`).\n\nGlobal and per-agent binds are **merged** (not replaced). Under `scope: \"shared\"`, per-agent binds are ignored.\n\nExample (read-only source + docker socket):\n\n* Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (`:ro` or `:rw`).\n* Sensitive mounts (e.g., `docker.sock`, secrets, SSH keys) should be `:ro` unless absolutely required.\n* Combine with `workspaceAccess: \"ro\"` if you only need read access to the workspace; bind modes stay independent.\n* See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for how binds interact with tool policy and elevated exec.\n\nDefault image: `openclaw-sandbox:bookworm-slim`\n\nNote: the default image does **not** include Node. If a skill needs Node (or\nother runtimes), either bake a custom image or install via\n`sandbox.docker.setupCommand` (requires network egress + writable root +\nroot user).\n\nSandboxed browser image:\n\nBy default, sandbox containers run with **no network**.\nOverride with `agents.defaults.sandbox.docker.network`.\n\nDocker installs and the containerized gateway live here:\n[Docker](/install/docker)\n\n## setupCommand (one-time container setup)\n\n`setupCommand` runs **once** after the sandbox container is created (not on every run).\nIt executes inside the container via `sh -lc`.\n\n* Global: `agents.defaults.sandbox.docker.setupCommand`\n* Per-agent: `agents.list[].sandbox.docker.setupCommand`\n\n* Default `docker.network` is `\"none\"` (no egress), so package installs will fail.\n* `readOnlyRoot: true` prevents writes; set `readOnlyRoot: false` or bake a custom image.\n* `user` must be root for package installs (omit `user` or set `user: \"0:0\"`).\n* Sandbox exec does **not** inherit host `process.env`. Use\n  `agents.defaults.sandbox.docker.env` (or a custom image) for skill API keys.\n\n## Tool policy + escape hatches\n\nTool allow/deny policies still apply before sandbox rules. If a tool is denied\nglobally or per-agent, sandboxing doesn’t bring it back.\n\n`tools.elevated` is an explicit escape hatch that runs `exec` on the host.\n`/exec` directives only apply for authorized senders and persist per session; to hard-disable\n`exec`, use tool policy deny (see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)).\n\n* Use `openclaw sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.\n* See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for the “why is this blocked?” mental model.\n  Keep it locked down.\n\n## Multi-agent overrides\n\nEach agent can override sandbox + tools:\n`agents.list[].sandbox` and `agents.list[].tools` (plus `agents.list[].tools.sandbox.tools` for sandbox tool policy).\nSee [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence.\n\n## Minimal enable example\n\n* [Sandbox Configuration](/gateway/configuration#agentsdefaults-sandbox)\n* [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools)\n* [Security](/gateway/security)",
  "code_samples": [
    {
      "code": "Security notes:\n\n* Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (`:ro` or `:rw`).\n* Sensitive mounts (e.g., `docker.sock`, secrets, SSH keys) should be `:ro` unless absolutely required.\n* Combine with `workspaceAccess: \"ro\"` if you only need read access to the workspace; bind modes stay independent.\n* See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for how binds interact with tool policy and elevated exec.\n\n## Images + setup\n\nDefault image: `openclaw-sandbox:bookworm-slim`\n\nBuild it once:",
      "language": "unknown"
    },
    {
      "code": "Note: the default image does **not** include Node. If a skill needs Node (or\nother runtimes), either bake a custom image or install via\n`sandbox.docker.setupCommand` (requires network egress + writable root +\nroot user).\n\nSandboxed browser image:",
      "language": "unknown"
    },
    {
      "code": "By default, sandbox containers run with **no network**.\nOverride with `agents.defaults.sandbox.docker.network`.\n\nDocker installs and the containerized gateway live here:\n[Docker](/install/docker)\n\n## setupCommand (one-time container setup)\n\n`setupCommand` runs **once** after the sandbox container is created (not on every run).\nIt executes inside the container via `sh -lc`.\n\nPaths:\n\n* Global: `agents.defaults.sandbox.docker.setupCommand`\n* Per-agent: `agents.list[].sandbox.docker.setupCommand`\n\nCommon pitfalls:\n\n* Default `docker.network` is `\"none\"` (no egress), so package installs will fail.\n* `readOnlyRoot: true` prevents writes; set `readOnlyRoot: false` or bake a custom image.\n* `user` must be root for package installs (omit `user` or set `user: \"0:0\"`).\n* Sandbox exec does **not** inherit host `process.env`. Use\n  `agents.defaults.sandbox.docker.env` (or a custom image) for skill API keys.\n\n## Tool policy + escape hatches\n\nTool allow/deny policies still apply before sandbox rules. If a tool is denied\nglobally or per-agent, sandboxing doesn’t bring it back.\n\n`tools.elevated` is an explicit escape hatch that runs `exec` on the host.\n`/exec` directives only apply for authorized senders and persist per session; to hard-disable\n`exec`, use tool policy deny (see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)).\n\nDebugging:\n\n* Use `openclaw sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.\n* See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for the “why is this blocked?” mental model.\n  Keep it locked down.\n\n## Multi-agent overrides\n\nEach agent can override sandbox + tools:\n`agents.list[].sandbox` and `agents.list[].tools` (plus `agents.list[].tools.sandbox.tools` for sandbox tool policy).\nSee [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence.\n\n## Minimal enable example",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "What gets sandboxed",
      "id": "what-gets-sandboxed"
    },
    {
      "level": "h2",
      "text": "Modes",
      "id": "modes"
    },
    {
      "level": "h2",
      "text": "Scope",
      "id": "scope"
    },
    {
      "level": "h2",
      "text": "Workspace access",
      "id": "workspace-access"
    },
    {
      "level": "h2",
      "text": "Custom bind mounts",
      "id": "custom-bind-mounts"
    },
    {
      "level": "h2",
      "text": "Images + setup",
      "id": "images-+-setup"
    },
    {
      "level": "h2",
      "text": "setupCommand (one-time container setup)",
      "id": "setupcommand-(one-time-container-setup)"
    },
    {
      "level": "h2",
      "text": "Tool policy + escape hatches",
      "id": "tool-policy-+-escape-hatches"
    },
    {
      "level": "h2",
      "text": "Multi-agent overrides",
      "id": "multi-agent-overrides"
    },
    {
      "level": "h2",
      "text": "Minimal enable example",
      "id": "minimal-enable-example"
    },
    {
      "level": "h2",
      "text": "Related docs",
      "id": "related-docs"
    }
  ],
  "url": "llms-txt#sandboxing",
  "links": []
}