Sandboxing — Developer Reference

Type definitions, policy filtering order, and implementation details for the WednesdayAI sandbox system.

Source files

File	What it defines
`src/config/types.agents-shared.ts`	`AgentSandboxConfig`
`src/config/types.tools.ts`	`AgentToolsConfig`, `ToolsConfig` (sandbox.tools sections)
`src/config/types.agents.ts`	`AgentConfig.sandbox`, `AgentConfig.tools`
`src/config/zod-schema.agent-runtime.ts`	`AgentSandboxSchema`, `ToolExecSchema` (Zod validation)

AgentSandboxConfig

// src/config/types.agents-shared.ts
export type AgentSandboxConfig = {
  mode?: "off" | "non-main" | "all";
  workspaceAccess?: "none" | "ro" | "rw";
  /**
   * - "spawned": only allow session tools to target sessions spawned from this session (default)
   * - "all": allow session tools to target any session
   */
  sessionToolsVisibility?: "spawned" | "all";
  /** "session" (default) | "agent" | "shared" */
  scope?: "session" | "agent" | "shared";
  /** Legacy alias for scope ("session" when true, "shared" when false). */
  perSession?: boolean;
  workspaceRoot?: string;
  /**
   * When true and a multi-lane is resolved: scope sandbox tool filesystem
   * access to the lane's effective workspace dir (per-lane content fencing).
   * Additive. Single-user runs are unaffected. Requires workspaceAccess: "rw"
   * for complete isolation.
   */
  fenceToLane?: boolean;
  docker?: SandboxDockerSettings;
  browser?: SandboxBrowserSettings;
  prune?: SandboxPruneSettings;
};

Zod schema (AgentSandboxSchema in src/config/zod-schema.agent-runtime.ts) uses .strict() + .superRefine() for cross-field validation (e.g. fenceToLane + workspaceAccess warning).

AgentConfig placement

// src/config/types.agents.ts
export type AgentConfig = {
  id: string;
  // ...
  sandbox?: AgentSandboxConfig; // per-agent sandbox overrides
  tools?: AgentToolsConfig; // per-agent tool policy
};

Agent-level sandbox overrides agents.defaults.sandbox field-by-field. Docker/browser/prune sub-objects are ignored when scope resolves to "shared".

Tool policy filtering order

Full 8-level pipeline (each level can only further restrict):

Tool profile (tools.profile or agents.list[].tools.profile)
Provider tool profile (tools.byProvider[provider].profile or per-agent)
Global tool policy (tools.allow / tools.deny)
Provider tool policy (tools.byProvider[provider].allow/deny)
Agent-specific tool policy (agents.list[].tools.allow/deny)
Agent provider policy (agents.list[].tools.byProvider[provider].allow/deny)
Sandbox tool policy (tools.sandbox.tools or agents.list[].tools.sandbox.tools)
Subagent tool policy (tools.subagents.tools)

deny wins at every level. Non-empty allow makes everything not listed implicitly blocked. agents.list[].tools.sandbox.tools replaces (not merges with) tools.sandbox.tools for that agent. Provider tool keys accept either provider (e.g. google-antigravity) or provider/model (e.g. openai/gpt-5.2).

Tool groups

Available group:* shorthands (expand in tool policies at all levels):

Group	Members
`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)

AgentToolsConfig sandbox section

// src/config/types.tools.ts
export type AgentToolsConfig = {
  // ...
  sandbox?: {
    tools?: {
      allow?: string[];
      deny?: string[];
    };
  };
};

This is the “sandbox tool policy” (level 7 above). It applies only when the session is sandboxed. agents.list[].tools.sandbox.tools replaces tools.sandbox.tools for that agent.

fenceToLane implementation details

fenceToLane: true is applied only when:

Workspace lanes are enabled on the agent.
The lane is resolved (not denied or absent).
The policy decision is "allowed".

Effect: sandbox tool filesystem access is scoped to the lane’s effective workspace directory. Bootstrap resolution (e.g. AGENTS.md selection) remains lane-aware and can still select lane-local files with persona fallback. Cross-field constraint: when fenceToLane: true and workspaceAccess is not "rw", a warning is logged at session setup. With "none" or "ro", scope-keyed directory seeding is used and two sessions sharing the same scope key can cross-read each other’s seeded files.

sessionToolsVisibility

Controls which sessions are targetable by session tools (sessions_list, sessions_send, etc.):

"spawned" (default) — only sessions spawned from this session.
"all" — any session.

Applies per-agent at the sandbox config level.

Elevated mode interaction

tools.elevated is an exec-only escape hatch. Elevated runs exec on the host, bypassing the sandbox. It does not grant additional tools and does not override tools.deny. tools.elevated.enabled — global baseline (default: true). agents.list[].tools.elevated.enabled — can only further restrict (both global + agent must allow). tools.elevated.allowFrom — per-provider sender allowlists. Mitigation patterns for developers building multi-agent setups:

{
  "tools": { "elevated": { "enabled": false } },
  "agents": {
    "list": [
      {
        "id": "restricted",
        "tools": {
          "deny": ["exec"],
          "elevated": { "enabled": false }
        }
      }
    ]
  }
}

Bind mount blocking

The sandbox blocks these bind sources at config-load time:

docker.sock (any path)
/etc, /proc, /sys, /dev
Parent mounts that would expose the above

network: "host" is blocked. network: "container:<id>" requires dangerouslyAllowContainerNamespaceJoin: true.

Sandbox config precedence (all fields)

agents.list[].sandbox.mode             > agents.defaults.sandbox.mode
agents.list[].sandbox.scope            > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot    > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess  > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.fenceToLane      > agents.defaults.sandbox.fenceToLane
agents.list[].sandbox.docker.*         > agents.defaults.sandbox.docker.*    (ignored for scope=shared)
agents.list[].sandbox.browser.*        > agents.defaults.sandbox.browser.*   (ignored for scope=shared)
agents.list[].sandbox.prune.*          > agents.defaults.sandbox.prune.*     (ignored for scope=shared)

Sandbox tool policy config shape

{
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["group:runtime", "group:fs"],
        "deny": ["browser"]
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "restricted",
        "tools": {
          "sandbox": {
            "tools": {
              "allow": ["read"],
              "deny": ["exec", "write", "edit"]
            }
          }
        }
      }
    ]
  }
}

Debug tooling

openclaw sandbox explain --json

Returns structured JSON with: mode, scope, workspaceAccess, fenceToLane, sessionToolsVisibility, isCurrentlySandboxed, sandboxToolPolicy (allow/deny/source), elevatedGates, fixItKeys. Related: Sandboxing (user) · Sandboxing (admin) · Exec Tool (developer)

Getting started

Gateway configuration

Channels

Automation

Observability

Core concepts

AI providers

Security

Maintenance

Admin

Channels (synced pages)

Gateway (synced pages)

Gateway security

Installation

Platforms

macOS app

More providers

Security

Web UI

Shohin

Sandboxing developer

Sandboxing — Developer Reference

Source files

AgentSandboxConfig

AgentConfig placement

Tool policy filtering order

Tool groups

AgentToolsConfig sandbox section

fenceToLane implementation details

sessionToolsVisibility

Elevated mode interaction

Bind mount blocking

Sandbox config precedence (all fields)

Sandbox tool policy config shape

Debug tooling

​Sandboxing — Developer Reference

​Source files

​AgentSandboxConfig

​AgentConfig placement

​Tool policy filtering order

​Tool groups

​AgentToolsConfig sandbox section

​fenceToLane implementation details

​sessionToolsVisibility

​Elevated mode interaction

​Bind mount blocking

​Sandbox config precedence (all fields)

​Sandbox tool policy config shape

​Debug tooling

Sandboxing — Developer Reference

Source files

AgentSandboxConfig

AgentConfig placement

Tool policy filtering order

Tool groups

AgentToolsConfig sandbox section

fenceToLane implementation details

sessionToolsVisibility

Elevated mode interaction

Bind mount blocking

Sandbox config precedence (all fields)

Sandbox tool policy config shape

Debug tooling