> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxing

> Run agent tools inside Docker containers to limit blast radius — modes, scope, workspace access, and how sandbox interacts with tool policy and elevated exec.

# Sandboxing

WednesdayAI can run **tools inside Docker containers** to reduce blast radius. Sandboxing is optional and off by default; when it is off, tools run on the host with the same permissions as the gateway process. The gateway process itself always stays on the host — only tool execution moves into a container.

This is not a perfect security boundary, but it materially limits filesystem and process access when the model does something it should not.

> [!WARNING]
>
> When `sandbox.mode` is `off` (the default), tool code runs with the same permissions as the gateway process. Install only plugins you trust, and consider enabling a sandbox for non-main sessions.

## What gets sandboxed

* Tool execution: `exec`, `read`, `write`, `edit`, `apply_patch`, `process`, and similar.
* An optional sandboxed browser (`agents.defaults.sandbox.browser`).

**Not** sandboxed:

* The gateway process itself.
* Any tool explicitly allowed to run on the host — in particular, **elevated exec runs on the host and bypasses sandboxing**.

## Modes

`agents.defaults.sandbox.mode` controls **when** sandboxing is used:

| Mode | Effect |
| - | - |
| `off` (default) | No sandboxing — tools run in the gateway process |
| `non-main` | Sandboxes all sessions except the main session |
| `all` | Every session runs in a sandbox |

> [!NOTE]
>
> `non-main` is based on `session.mainKey` (default `"main"`), not agent id. Group and channel sessions use their own keys, so they count as non-main and **will** be sandboxed in `non-main` mode — a common surprise.

## Scope

`agents.defaults.sandbox.scope` controls **how many containers** are created:

| Scope | Effect |
| - | - |
| `session` (default) | One container per session |
| `agent` | One container per agent |
| `shared` | One container shared by all sandboxed sessions |

## Workspace access

`agents.defaults.sandbox.workspaceAccess` controls **what the sandbox can see**:

| Value | Effect |
| - | - |
| `none` (default) | Tools see a fresh 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` |

Inbound media is copied into the active sandbox workspace (`media/inbound/*`). With `workspaceAccess: "none"`, eligible skills are mirrored into the sandbox workspace so the (sandbox-rooted) `read` tool can see them.

## Session tools visibility

`agents.defaults.sandbox.sessionToolsVisibility` controls which sessions a **sandboxed** session can see and message through the session tools (`sessions_list`, `sessions_history`, `sessions_send`):

| Value | Effect |
| - | - |
| `spawned` (default) | Sandboxed sessions are forced to `tree` visibility regardless of `tools.sessions.visibility`, and a sandboxed non-subagent session can only target sessions it spawned |
| `all` | No sandbox clamp — `tools.sessions.visibility` governs |

This key is only read from `agents.defaults.sandbox`; a per-agent `agents.list[].sandbox` block does not override it.

## Custom bind mounts

`agents.defaults.sandbox.docker.binds` mounts additional host directories. Format: `host:container:mode`, e.g. `"/home/user/source:/source:ro"`. Global and per-agent binds are merged (under `scope: "shared"`, per-agent binds are ignored).

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
  },
}
```

> [!WARNING]
>
> Binds bypass the sandbox filesystem and expose host paths with whatever mode you set. WednesdayAI blocks dangerous sources (`/etc`, `/proc`, `/sys`, `/dev`, `/root`, `/boot`, Docker socket paths such as `/var/run/docker.sock`, and the `/run`/`/var/run` directories that alias them, plus parent mounts that would expose any of these). These blocks are absolute — the `dangerouslyAllow*` overrides below do not lift them. Mount secrets and credentials `:ro` unless absolutely required — binding `/var/run/docker.sock` effectively hands host control to the sandbox.

### Dangerous overrides

Three `agents.defaults.sandbox.docker.dangerouslyAllow*` booleans lift sandbox security blocks. All default to `false`.

| Key | Block it lifts |
| - | - |
| `dangerouslyAllowReservedContainerTargets` | Allows bind mounts whose **target** inside the container is a reserved path (`/workspace`, `/agent`) |
| `dangerouslyAllowExternalBindSources` | Allows bind **sources** outside the runtime-allowlisted roots (the sandbox workspace and agent workspace roots) |
| `dangerouslyAllowContainerNamespaceJoin` | Allows `network: "container:<id>"`, joining another container's network namespace |

> [!WARNING]
>
> These flags remove guardrails that keep the sandbox contained. `dangerouslyAllowReservedContainerTargets` can shadow WednesdayAI's own sandbox mounts; `dangerouslyAllowExternalBindSources` exposes arbitrary host paths (only the absolute denylist above still applies); `dangerouslyAllowContainerNamespaceJoin` defeats network isolation. Use them only for containers you trust as much as the host, and remove them as soon as you can.

## Images and setup

The default image is `openclaw-sandbox:bookworm-slim`. Build it once:

```bash theme={"dark"}
scripts/sandbox-setup.sh
```

The default image does **not** include Node. For a richer image with `curl`, `jq`, `nodejs`, `python3`, and `git`:

```bash theme={"dark"}
scripts/sandbox-common-setup.sh
# then set agents.defaults.sandbox.docker.image to openclaw-sandbox-common:bookworm-slim
```

For the sandboxed browser:

```bash theme={"dark"}
scripts/sandbox-browser-setup.sh
```

By default, sandbox containers run with **no network** (`docker.network: "none"`). Override with `agents.defaults.sandbox.docker.network`. `network: "host"` and `network: "container:<id>"` are blocked by default (see [Dangerous overrides](#dangerous-overrides) for the namespace-join break-glass override).

`openclaw doctor` checks the sandbox image and offers to build or switch it when sandboxing is enabled but the image is missing.

## Resource limits and hardening

`agents.defaults.sandbox.docker` caps what a sandbox container can consume. Unset keys fall back to the Docker daemon default.

| Key | Default | Effect |
| - | - | - |
| `cpus` | unset (Docker default) | CPU limit, e.g. `0.5`, `1`, `2` |
| `memory` | unset (Docker default) | Memory limit, e.g. `"512m"`, `"2g"`, or bytes as a number |
| `memorySwap` | unset (Docker default) | Memory+swap limit (same format as `memory`) |
| `pidsLimit` | unset (Docker default) | Process-count limit (`0` = Docker default) |
| `ulimits` | unset | Per-name ulimits, e.g. `{ nofile: "1024:4096" }` (`"soft:hard"` string, number, or `{ soft, hard }`) |

Isolation defaults are already hardened: `readOnlyRoot: true`, `capDrop: ["ALL"]`, and tmpfs mounts at `/tmp`, `/var/tmp`, `/run`. `seccompProfile` and `apparmorProfile` accept a path or profile name; `unconfined` is rejected for both.

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      sandbox: {
        docker: { cpus: 1, memory: "512m", pidsLimit: 256 },
      },
    },
  },
}
```

Per-agent `docker` blocks override these keys per agent; under `scope: "shared"` the per-agent block is ignored (same rule as binds). Changes apply to containers created after the next config load — existing containers keep their settings until recreated.

## Auto-prune

`agents.defaults.sandbox.prune` force-removes sandbox and sandbox-browser containers (`docker rm -f` plus their registry entries, running or not). The prune pass runs at most every 5 minutes; a container is pruned when **either** condition hits:

| Key | Default | Effect |
| - | - | - |
| `idleHours` | `24` | Prune when unused for more than N hours (`0` disables the idle check) |
| `maxAgeDays` | `7` | Prune when older than N days (`0` disables the age check) |

Set both to `0` to disable auto-prune entirely. Per-agent `prune` blocks are ignored under `scope: "shared"`.

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      sandbox: { prune: { idleHours: 8, maxAgeDays: 3 } },
    },
  },
}
```

## Sandbox vs tool policy vs elevated

Three related but distinct controls decide whether a tool runs and where:

1. **Sandbox** (`agents.defaults.sandbox.*`) decides **where** tools run — Docker vs host.
2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which** tools are available.
3. **Elevated** (`tools.elevated.*`) is an exec-only escape hatch to run on the host while sandboxed.

Rules of thumb:

* Tool policy is the hard stop. `deny` always wins; if `allow` is non-empty, everything else is blocked.
* Tool policy applies **before** sandbox rules — sandboxing never re-enables a denied tool.
* `/exec` only adjusts per-session exec defaults for authorized senders; it cannot override a denied `exec` tool.
* Elevated does not grant extra tools and does not override allow/deny. `/elevated on` runs `exec` on the host (approvals may still apply); `/elevated full` skips exec approvals for the session.

### Debugging "why is this blocked?"

```bash theme={"dark"}
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```

It prints the effective sandbox mode, scope, and workspace access, whether the current session is sandboxed, the effective sandbox tool allow/deny (and where it came from), and the elevated gates with fix-it config keys.

### Tool groups

Sandbox tool policy accepts `group:*` shorthands:

| Group | Expands to |
| - | - |
| `group:runtime` | `exec`, `bash`, `process` |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
| `group:ui` | `browser`, `canvas` |
| `group:automation` | `cron`, `gateway` |
| `group:messaging` | `message` |
| `group:nodes` | `nodes` |
| `group:openclaw` | all built-in tools (excludes provider plugins) |

## Minimal enable example

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}
```

***

**Related:** [Security hardening](https://docs.wednesdayai.dev/next/admin/security.md) · [Gateway configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md) · [Doctor](https://docs.wednesdayai.dev/next/admin/doctor.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.