Documentation Index

Fetch the complete documentation index at: https://cryptoclawdocs.termix.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Sandboxing

​

What gets sandboxed

• Tool execution (exec, read, write, edit, apply_patch, process, etc.).
• Optional sandboxed browser (agents.defaults.sandbox.browser).
  • By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it. Configure via agents.defaults.sandbox.browser.autoStart and agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • By default, sandbox browser containers use a dedicated Docker network (openclaw-sandbox-browser) instead of the global bridge network. Configure with agents.defaults.sandbox.browser.network.
  • Optional agents.defaults.sandbox.browser.cdpSourceRange restricts container-edge CDP ingress with a CIDR allowlist (for example 172.21.0.1/32).
  • noVNC observer access is password-protected by default; OpenClaw emits a short-lived token URL that serves a local bootstrap page and opens noVNC with password in URL fragment (not query/header logs).
  • agents.defaults.sandbox.browser.allowHostControl lets sandboxed sessions target the host browser explicitly.
  • Optional allowlists gate target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

• The Gateway process itself.
• Any tool explicitly allowed to run on the host (e.g. tools.elevated).
  • Elevated exec runs on the host and bypasses sandboxing.
  • If sandboxing is off, tools.elevated does not change execution (already on host). See Elevated Mode.

​

Modes

• "off": no sandboxing.
• "non-main": sandbox only non-main sessions (default if you want normal chats on host).
• "all": every session runs in a sandbox. Note: "non-main" is based on session.mainKey (default "main"), not agent id. Group/channel sessions use their own keys, so they count as non-main and will be sandboxed.

​

Scope

• "session" (default): one container per session.
• "agent": one container per agent.
• "shared": one container shared by all sandboxed sessions.

​

Workspace access

• "none" (default): tools see a sandbox workspace under ~/.openclaw/sandboxes.
• "ro": mounts the agent workspace read-only at /agent (disables write/edit/apply_patch).
• "rw": mounts the agent workspace read/write at /workspace.

​

Custom bind mounts

• When set (including []), it replaces agents.defaults.sandbox.docker.binds for the browser container.
• When omitted, the browser container falls back to agents.defaults.sandbox.docker.binds (backwards compatible).

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

• Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (:ro or :rw).
• OpenClaw blocks dangerous bind sources (for example: docker.sock, /etc, /proc, /sys, /dev, and parent mounts that would expose them).
• Sensitive mounts (secrets, SSH keys, service credentials) should be :ro unless absolutely required.
• Combine with workspaceAccess: "ro" if you only need read access to the workspace; bind modes stay independent.
• See Sandbox vs Tool Policy vs Elevated for how binds interact with tool policy and elevated exec.

​

Images + setup

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• --no-sandbox and --disable-setuid-sandbox when noSandbox is enabled.
• The three graphics hardening flags (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) are optional and are useful when containers lack GPU support. Set OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 if your workload requires WebGL or other 3D/browser features.
• --disable-extensions is enabled by default and can be disabled with OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 for extension-reliant flows.
• --renderer-process-limit=2 is controlled by OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, where 0 keeps Chromium’s default.

• network: "host" is blocked.
• network: "container:<id>" is blocked by default (namespace join bypass risk).
• Break-glass override: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

setupCommand (one-time container setup)

• Global: agents.defaults.sandbox.docker.setupCommand
• Per-agent: agents.list[].sandbox.docker.setupCommand

• Default docker.network is "none" (no egress), so package installs will fail.
• docker.network: "container:<id>" requires dangerouslyAllowContainerNamespaceJoin: true and is break-glass only.
• readOnlyRoot: true prevents writes; set readOnlyRoot: false or bake a custom image.
• user must be root for package installs (omit user or set user: "0:0").
• Sandbox exec does not inherit host process.env. Use agents.defaults.sandbox.docker.env (or a custom image) for skill API keys.

​

Tool policy + escape hatches

• Use openclaw sandbox explain to inspect effective sandbox mode, tool policy, and fix-it config keys.
• See Sandbox vs Tool Policy vs Elevated for the “why is this blocked?” mental model. Keep it locked down.

​

Multi-agent overrides

​

Minimal enable example

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

​

Related docs

• Sandbox Configuration
• Multi-Agent Sandbox & Tools
• Security