Skip to main content

​
Sandboxing — User Guide

WednesdayAI can run your agent’s tools inside Docker containers to reduce blast radius. If something goes wrong, sandbox limits what the agent can access. This is optional — if sandboxing is off, tools run directly on the host.

​
What gets sandboxed

When enabled, these tools run inside the container:
  • exec, read, write, edit, apply_patch, process
  • Sandboxed browser (if configured)
Not sandboxed:
  • The Gateway process itself
  • Elevated exec (tools.elevated) — that always runs on the host

​
Modes

agents.defaults.sandbox.mode: Tip: "non-main" is a common choice — your personal chat runs on the host while group chats are isolated.

​
What the sandbox can see (workspace access)

agents.defaults.sandbox.workspaceAccess:

​
Enable sandboxing (minimal setup)

Before enabling, build the sandbox image once:

​
Per-agent sandbox

Different agents can have different sandbox settings:

​
Tool restrictions alongside sandboxing

Sandboxing controls where tools run. Tool policy controls which tools are available:
A tool denied by policy is blocked even inside a sandbox.

​
Common “why is this blocked?” fixes

“I’m sandboxed but I thought this was my main session” If your mode is "non-main", group and channel chats are always treated as non-main and get sandboxed. To disable sandboxing for a specific agent, set agents.list[].sandbox.mode: "off" for that agent. “A tool I need is blocked” Use openclaw sandbox explain to see what’s blocking it:
This shows effective sandbox mode, tool policy, and the config key to change.

​
Workspace lane fencing

If you use workspace lanes, add fenceToLane: true to restrict the sandbox filesystem to your lane’s workspace (instead of allowing access up to the shared root):
Requires workspaceAccess: "rw". Related: Exec Tool · Sandbox vs Tool Policy vs Elevated