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

Sandboxing

OpenClaw can run tools inside sandbox backends to reduce blast radius. This is optional and controlled by configuration (

text

agents.defaults.sandbox

text

agents.list[].sandbox

). If sandboxing is off, tools run on the host. The Gateway stays on the host; tool execution runs in an isolated sandbox when enabled.

note

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

What gets sandboxed

Tool execution (
text
exec
,
text
read
,
text
write
,
text
edit
,
text
apply_patch
,
text
process
, etc.).
Optional sandboxed browser (
text
agents.defaults.sandbox.browser
).

Not sandboxed:

The Gateway process itself.
Any tool explicitly allowed to run outside the sandbox (e.g.
text
tools.elevated
).
- Elevated exec bypasses sandboxing and uses the configured escape path (
  text
  gateway
  by default, or
  text
  node
  when the exec target is
  text
  node
  ).
- If sandboxing is off,
  text
  tools.elevated
  does not change execution (already on host). See Elevated Mode.

Modes

text

agents.defaults.sandbox.mode

controls when sandboxing is used:

No sandboxing. Sandbox only **non-main** sessions (default if you want normal chats on host).


text
`"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.

Every session runs in a sandbox.

Scope

text

agents.defaults.sandbox.scope

controls how many containers are created:

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

Backend

text

agents.defaults.sandbox.backend

controls which runtime provides the sandbox:

text
"docker"
(default when sandboxing is enabled): local Docker-backed sandbox runtime.
text
"ssh"
: generic SSH-backed remote sandbox runtime.
text
"openshell"
: OpenShell-backed sandbox runtime.

SSH-specific config lives under

text

agents.defaults.sandbox.ssh

. OpenShell-specific config lives under

text

plugins.entries.openshell.config

Choosing a backend

	Docker	SSH	OpenShell
Where it runs	Local container	Any SSH-accessible host	OpenShell managed sandbox
Setup	text `scripts/sandbox-setup.sh`	SSH key + target host	OpenShell plugin enabled
Workspace model	Bind-mount or copy	Remote-canonical (seed once)	text `mirror` or text `remote`
Network control	text `docker.network` (default: none)	Depends on remote host	Depends on OpenShell
Browser sandbox	Supported	Not supported	Not supported yet
Bind mounts	text `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

Sandboxing is off by default. If you enable sandboxing and do not choose a backend, OpenClaw uses the Docker backend. It executes tools and sandbox browsers locally via the Docker daemon socket (

text

/var/run/docker.sock

). Sandbox container isolation is determined by Docker namespaces.

To expose host GPUs to Docker sandboxes, set

text

agents.defaults.sandbox.docker.gpus

or the per-agent

text

agents.list[].sandbox.docker.gpus

override. The value is passed to Docker's

text

--gpus

flag as a separate argument, for example

text

"all"

text

"device=GPU-uuid"

, and requires a compatible host runtime such as NVIDIA Container Toolkit.

warning

**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
text
openclaw.json

text
workspace
configuration MUST contain the Host's absolute path (e.g.
text
/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
text
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 (
text
-v /home/user/.openclaw:/home/user/.openclaw
).

If you map paths internally without absolute host parity, OpenClaw natively throws an

text

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

text

backend: "ssh"

when you want OpenClaw to sandbox

text

exec

, file tools, and media reads on an arbitrary SSH-accessible machine.


json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Or use SecretRefs / inline contents instead of local files:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

OpenShell backend

Use

text

backend: "openshell"

when you want OpenClaw to sandbox tools in an OpenShell-managed remote environment. For the full setup guide, configuration reference, and workspace mode comparison, see the dedicated OpenShell page.

OpenShell reuses the same core SSH transport and remote filesystem bridge as the generic SSH backend, and adds OpenShell-specific lifecycle (

text

sandbox create/get/delete

text

sandbox ssh-config

) plus the optional

text

mirror

workspace mode.


json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}

OpenShell modes:

text
mirror
(default): local workspace stays canonical. OpenClaw syncs local files into OpenShell before exec and syncs the remote workspace back after exec.
text
remote
: OpenShell workspace is canonical after the sandbox is created. OpenClaw seeds the remote workspace once from the local workspace, then file tools and exec run directly against the remote sandbox without syncing changes back.

Workspace modes

OpenShell has two workspace models. This is the part that matters most in practice.

Use `plugins.entries.openshell.config.mode: "mirror"` when you want the **local workspace to stay canonical**.


text
Behavior:

* Before `exec`, OpenClaw syncs the local workspace into the OpenShell sandbox.
* After `exec`, OpenClaw syncs the remote workspace back to the local workspace.
* File tools still operate through the sandbox bridge, but the local workspace remains the source of truth between turns.

Use this when:

* you edit files locally outside OpenClaw and want those changes to show up in the sandbox automatically
* you want the OpenShell sandbox to behave as much like the Docker backend as possible
* you want the host workspace to reflect sandbox writes after each exec turn

Tradeoff: extra sync cost before and after exec.

Use `plugins.entries.openshell.config.mode: "remote"` when you want the **OpenShell workspace to become canonical**.


text
Behavior:

* When the sandbox is first created, OpenClaw seeds the remote workspace from the local workspace once.
* After that, `exec`, `read`, `write`, `edit`, and `apply_patch` operate directly against the remote OpenShell workspace.
* OpenClaw does **not** sync remote changes back into the local workspace after exec.
* Prompt-time media reads still work because file and media tools read through the sandbox bridge instead of assuming a local host path.
* Transport is SSH into the OpenShell sandbox returned by `openshell sandbox ssh-config`.

Important consequences:

* If you edit files on the host outside OpenClaw after the seed step, the remote sandbox will **not** see those changes automatically.
* If the sandbox is recreated, the remote workspace is seeded from the local workspace again.
* With `scope: "agent"` or `scope: "shared"`, that remote workspace is shared at that same scope.

Use this when:

* the sandbox should live primarily on the remote OpenShell side
* you want lower per-turn sync overhead
* you do not want host-local edits to silently overwrite remote sandbox state

Choose

text

mirror

if you think of the sandbox as a temporary execution environment. Choose

text

remote

if you think of the sandbox as the real workspace.

OpenShell lifecycle

OpenShell sandboxes are still managed through the normal sandbox lifecycle:

text
openclaw sandbox list
shows OpenShell runtimes as well as Docker runtimes
text
openclaw sandbox recreate
deletes the current runtime and lets OpenClaw recreate it on next use
prune logic is backend-aware too

For

text

remote

mode, recreate is especially important:

recreate deletes the canonical remote workspace for that scope
the next use seeds a fresh remote workspace from the local workspace

For

text

mirror

mode, recreate mainly resets the remote execution environment because the local workspace remains canonical anyway.

Workspace access

text

agents.defaults.sandbox.workspaceAccess

controls what the sandbox can see:

Tools see a sandbox workspace under `~/.openclaw/sandboxes`. Mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`). Mounts the agent workspace read/write at `/workspace`.

With the OpenShell backend:

text
mirror
mode still uses the local workspace as the canonical source between exec turns
text
remote
mode uses the remote OpenShell workspace as the canonical source after the initial seed
text
workspaceAccess: "ro"
and
text
"none"
still restrict write behavior the same way

Inbound media is copied into the active sandbox workspace (

text

media/inbound/*

note

**Skills note:** the `read` tool is sandbox-rooted. With `workspaceAccess: "none"`, OpenClaw mirrors eligible skills into the sandbox workspace (`.../skills`) so they can be read. With `"rw"`, workspace skills are readable from `/workspace/skills`.

Custom bind mounts

text

agents.defaults.sandbox.docker.binds

mounts additional host directories into the container. Format:

text

host:container:mode

(e.g.,

text

"/home/user/source:/source:rw"

Global and per-agent binds are merged (not replaced). Under

text

scope: "shared"

, per-agent binds are ignored.

text

agents.defaults.sandbox.browser.binds

mounts additional host directories into the sandbox browser container only.

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

Example (read-only source + an extra data directory):


json5
{
  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"],
          },
        },
      },
    ],
  },
}

warning

**Bind security**

Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (
text
:ro
or
text
:rw
).
OpenClaw blocks dangerous bind sources (for example:
text
docker.sock
,
text
/etc
,
text
/proc
,
text
/sys
,
text
/dev
, and parent mounts that would expose them).
OpenClaw also blocks common home-directory credential roots such as
text
~/.aws
,
text
~/.cargo
,
text
~/.config
,
text
~/.docker
,
text
~/.gnupg
,
text
~/.netrc
,
text
~/.npm
, and
text
~/.ssh
.
Bind validation is not just string matching. OpenClaw normalizes the source path, then resolves it again through the deepest existing ancestor before re-checking blocked paths and allowed roots.
That means symlink-parent escapes still fail closed even when the final leaf does not exist yet. Example:
text
/workspace/run-link/new-file
still resolves as
text
/var/run/...
if
text
run-link
points there.
Allowed source roots are canonicalized the same way, so a path that only looks inside the allowlist before symlink resolution is still rejected as
text
outside allowed roots
.
Sensitive mounts (secrets, SSH keys, service credentials) should be
text
:ro
unless absolutely required.
Combine with
text
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 and setup

Default Docker image:

text

openclaw-sandbox:bookworm-slim

Build the default image

```bash} scripts/sandbox-setup.sh ```


text
The default image does **not** include Node. If a skill needs Node (or other runtimes), either bake a custom image or install via `sandbox.docker.setupCommand` (requires network egress + writable root + root user).

OpenClaw does not silently substitute plain `debian:bookworm-slim` when `openclaw-sandbox:bookworm-slim` is missing. Sandbox runs that target the default image fail fast with a build instruction until you run `scripts/sandbox-setup.sh`, because the bundled image carries `python3` for sandbox write/edit helpers.

Optional: build the common image

For a more functional sandbox image with common tooling (for example `curl`, `jq`, `nodejs`, `python3`, `git`):


text
```bash}
scripts/sandbox-common-setup.sh
```

Then set `agents.defaults.sandbox.docker.image` to `openclaw-sandbox-common:bookworm-slim`.

Optional: build the sandbox browser image

```bash} scripts/sandbox-browser-setup.sh ```

By default, Docker sandbox containers run with no network. Override with

text

agents.defaults.sandbox.docker.network

Docker installs and the containerized gateway live here: Docker

For Docker gateway deployments,

text

scripts/docker/setup.sh

can bootstrap sandbox config. Set

text

OPENCLAW_SANDBOX=1

(or

text

true

text

yes

text

on

) to enable that path. You can override socket location with

text

OPENCLAW_DOCKER_SOCKET

. Full setup and env reference: Docker.

setupCommand (one-time container setup)

text

setupCommand

runs once after the sandbox container is created (not on every run). It executes inside the container via

text

sh -lc

Paths:

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

Tool policy and escape hatches

Tool allow/deny policies still apply before sandbox rules. If a tool is denied globally or per-agent, sandboxing doesn't bring it back.

text

tools.elevated

is an explicit escape hatch that runs

text

exec

outside the sandbox (

text

gateway

by default, or

text

node

when the exec target is

text

node

text

/exec

directives only apply for authorized senders and persist per session; to hard-disable

text

exec

, use tool policy deny (see Sandbox vs Tool Policy vs Elevated).

Debugging:

Use
text
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

Each agent can override sandbox + tools:

text

agents.list[].sandbox

and

text

agents.list[].tools

(plus

text

agents.list[].tools.sandbox.tools

for sandbox tool policy). See Multi-Agent Sandbox & Tools for precedence.

Minimal enable example


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

Multi-Agent Sandbox & Tools — per-agent overrides and precedence
OpenShell — managed sandbox backend setup, workspace modes, and config reference
Sandbox configuration
Sandbox vs Tool Policy vs Elevated — debugging "why is this blocked?"
Security

OpenClaw Docs

Sandboxing

note

What gets sandboxed

Modes

Scope

Backend

Choosing a backend

Docker backend

warning

SSH backend

OpenShell backend

Workspace modes

OpenShell lifecycle

Workspace access

note

Custom bind mounts

warning

Images and setup

Build the default image

Optional: build the common image

Optional: build the sandbox browser image

setupCommand (one-time container setup)

Tool policy and escape hatches

Multi-agent overrides

Minimal enable example

Related