Sandboxing

OpenClaw can run tool execution inside a sandbox backend to reduce blast radius. Sandboxing is off by default and controlled by agents.defaults.sandbox (global), agents.entries.*.sandbox (per-agent), or a required creator-role sandbox policy. The Gateway process always stays on the host; only tool execution moves into the sandbox when enabled.

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

Sandboxing pages

This page is an index. The sandbox reference is documented on twelve pages. Open the page that matches what you are configuring.

Page	Read it when
What gets sandboxed	You want to know exactly which execution moves into the sandbox.
Modes, scope, and backend	You are deciding which sessions run sandboxed and how they share environments.
Supported capability matrix	You are comparing Docker, SSH, and OpenShell before choosing a backend.
Docker backend	You are running the default local backend or enabling the sandboxed browser.
Podman backend	You are using Podman instead of Docker for sandboxed tool execution.
SSH backend	You are offloading sandboxed tool execution to a remote machine over SSH.
OpenShell backend	You are sandboxing tools in an OpenShell-managed remote environment.
Crabbox backend	You want tool execution on a Crabbox-leased cloud box while the agent stays local.
Workspace access	You are deciding what the sandbox can see of the agent workspace.
Multiple folders for one agent	One sandboxed agent needs more than its primary workspace.
Images and setup	You need to build or customize a sandbox image.
setupCommand (one-time container setup)	You need to run one-time setup inside a newly created sandbox container.

Where each section moved

Every anchor this page used to publish is kept here, so an existing link such as /gateway/sandboxing#images-and-setup still resolves. Each entry points at the page that now holds the content.

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. tools.elevated is an explicit escape hatch that runs exec outside the sandbox (gateway by default, or node when the exec target is node). /exec directives only apply for authorized senders and persist per session; to hard-disable exec, use tool policy deny (see Sandbox vs Tool Policy vs Elevated). Debugging:

openclaw sandbox list shows sandbox containers, status, image match, age, idle time, and associated session/agent.
openclaw sandbox explain [--session <key>] [--agent <id>] inspects effective sandbox mode, host workspace, runtime workdir, Docker mounts, tool policy, and fix-it config keys. Its workspaceRoot field remains the configured sandbox root; effectiveHostWorkspaceRoot shows where the active workspace actually lives.
openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] removes containers/environments so they get recreated with current config on next use.
See Sandbox vs Tool Policy vs Elevated for the “why is this blocked?” mental model.

Multi-agent overrides

Each agent can override sandbox + tools: agents.entries.*.sandbox and agents.entries.*.tools (plus agents.entries.*.tools.sandbox.tools for sandbox tool policy). See Multi-Agent Sandbox & Tools for precedence.

Minimal enable example

{
  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 sandbox — manage sandbox runtimes and inspect the effective sandbox policy
Cloud Workers — dispatching session work to throwaway cloud machines; its managed workspace is not an OS sandbox

Gateway

Remote access

Security

Nodes and media

Web interfaces

Sandboxing pages

Where each section moved

Tool policy and escape hatches

Multi-agent overrides

Minimal enable example

​Sandboxing pages

​Where each section moved

​Tool policy and escape hatches

​Multi-agent overrides

​Minimal enable example

​Related

Sandboxing pages

Where each section moved

Tool policy and escape hatches

Multi-agent overrides

Minimal enable example

Related