Sandbox Execution

Contents

Overview

flowchart LR
  subgraph Config["SandboxConfig"]
    Mode["Mode: off | non-main | all"]
    Backend["Backend: Docker | SSH"]
    Policy["Tool Policy"]
  end
  subgraph Resolution["Sandbox Resolution"]
    Resolve["Resolve sandbox mode"]
    Select["Select backend"]
    Mount["Configure mounts"]
  end
  subgraph Execution["Container Lifecycle"]
    Start["Start container"]
    Tool["Execute tool"]
    Idle["Idle detection"]
    Cleanup["Cleanup / remove"]
  end
  Mode --> Resolve
  Backend --> Select
  Policy --> Select
  Resolve --> Select
  Select --> Mount
  Mount --> Start
  Start --> Tool
  Tool --> Idle
  Idle --> Cleanup

The sandbox resolution pipeline evaluates whether the current tool call requires sandboxing (based on mode), selects the appropriate backend, configures workspace mounts, starts or reuses a container, executes the tool inside it, and monitors for idle timeout or maximum age expiry.

Decision Points

How It Works

SandboxConfig & SandboxContext Types

The sandbox system is configured through two core types defined in sandbox/types.ts. SandboxConfig is the user-facing configuration; SandboxContext is the runtime state after a sandbox is created:

// sandbox/types.ts — core configuration types
interface SandboxConfig {
  mode: "off" | "non-main" | "all";   // When to sandbox
  backend: "docker" | "ssh";           // Isolation backend
  workspaceRoot?: string;              // Override workspace root
  dockerImage?: string;                // Custom Docker image
  sshConfig?: SshConfig;               // SSH backend settings
  browser?: BrowserConfig;             // Browser automation config
  toolPolicies?: ToolPolicy[];         // Per-tool overrides
}

interface SandboxContext {
  containerName: string;               // Running container ID/name
  workspaceMounts: WorkspaceMount[];   // Active bind mounts
  dockerConfig: DockerConfig;          // Resolved Docker settings
  browserBridgeUrls?: {                // CDP bridge endpoints
    http: string;                      // http://localhost:9222
    ws: string;                        // ws://localhost:9222
  };
  scope: "session" | "agent" | "shared";
  createdAt: Date;
  lastActivityAt: Date;
}

interface WorkspaceMount {
  hostPath: string;                    // Path on host machine
  containerPath: string;               // Path inside container
  readOnly: boolean;                   // Mount as read-only?
}

interface SshConfig {
  host: string;
  port: number;
  username: string;
  privateKeyPath?: string;
  password?: string;
}

Default Configuration Constants

The sandbox module provides sensible defaults for every configurable value:

// sandbox/defaults.ts — default constants
import path from "node:path";

// Workspace
const STATE_DIR = process.env.OPENCLAW_STATE_DIR ?? path.join(
  process.env.HOME ?? "/root", ".openclaw"
);
export const DEFAULT_SANDBOX_WORKSPACE_ROOT = path.join(STATE_DIR, "sandboxes");
export const DEFAULT_SANDBOX_IMAGE = "openclaw-sandbox:bookworm-slim";

// Browser automation
export const DEFAULT_SANDBOX_BROWSER_CDP_PORT = 9222;
export const DEFAULT_SANDBOX_BROWSER_AUTOSTART_TIMEOUT_MS = 12000;

// Lifecycle
export const DEFAULT_SANDBOX_IDLE_HOURS = 24;
export const DEFAULT_SANDBOX_MAX_AGE_DAYS = 7;

// Tool allow-list
export const DEFAULT_TOOL_ALLOW = [
  "exec", "process",
  "read", "write", "edit", "apply_patch",
  "image",
  "sessions_list", "sessions_history",
  "sessions_send", "sessions_spawn", "sessions_yield",
  "subagents", "session_status",
];

Workspace Mounting

The sandbox mounts two directories into the container: the agent workspace at /agent and the user’s current working directory at /workspace. The agent workspace is read-write (for state persistence); the user workspace defaults to read-only but can be made writable:

Container State Machine

Containers follow a deterministic lifecycle managed by the sandbox runtime:

stateDiagram-v2
  [*] --> Idle
  Idle --> Starting : tool request
  Starting --> InUse : container ready
  Starting --> Failed : startup timeout
  InUse --> Idle : tool complete
  InUse --> InUse : another tool request
  Idle --> Terminating : idle timeout or max age
  Terminating --> Removed : cleanup complete
  Failed --> Removed : cleanup
  Removed --> [*]

Containers transition through five states. The Idle → Starting transition occurs on the first tool request. Once In Use, subsequent tool requests reuse the running container. After the last tool completes, the container returns to Idle and starts an idle timer. If no new requests arrive within DEFAULT_SANDBOX_IDLE_HOURS (24h), or the container exceeds DEFAULT_SANDBOX_MAX_AGE_DAYS (7d), it transitions to Terminating and is removed.

Sandbox Scope

The scope determines container sharing across agent runs:

ACP Sandbox Modes

The Agent Context Protocol (ACP) defines two sandbox inheritance modes for child agents spawned via sessions-spawn-tool.ts:

// ACP sandbox inheritance modes
type AcpSandboxMode = "inherit" | "require";

interface AcpSpawnOptions {
  sandboxMode: AcpSandboxMode;
  // "inherit" — child uses parent's sandbox container
  //   Pro: no startup overhead, shared state
  //   Con: child can see parent's files
  // "require" — child gets its own sandbox
  //   Pro: full isolation from parent
  //   Con: container startup latency

  toolPolicies?: ToolPolicy[];  // Child-specific overrides
}

// Example: spawn a sandboxed child for untrusted code review
const child = await spawnAgent({
  sandboxMode: "require",       // Isolated sandbox
  toolPolicies: [
    { tool: "exec", allow: false },  // No code execution
    { tool: "read", allow: true },   // Read-only access
  ],
});

Sandbox Resolution Flow

sequenceDiagram
  participant Agent as Agent Runtime
  participant Config as SandboxConfig
  participant Resolver as Sandbox Resolver
  participant Docker as Docker Backend
  participant Container as Container
  participant Tool as Tool Executor

  Agent->>Config: read sandbox settings
  Config-->>Agent: mode, backend, policies
  Agent->>Resolver: resolveSandbox(toolName, config)
  alt mode = "off"
    Resolver-->>Agent: no sandbox (host execution)
  else mode = "non-main" and isMainAgent
    Resolver-->>Agent: no sandbox (main agent exempt)
  else mode = "all" or non-main agent
    Resolver->>Docker: findOrCreateContainer(scope)
    alt Existing container available
      Docker-->>Resolver: reuse container
    else No container
      Docker->>Container: create + start
      Docker->>Container: mount workspaces
      Container-->>Docker: ready
      Docker-->>Resolver: new SandboxContext
    end
    Resolver->>Resolver: checkToolPolicy(toolName)
    alt Tool allowed
      Resolver->>Tool: execute inside container
      Tool-->>Resolver: result
      Resolver->>Container: update lastActivityAt
    else Tool denied
      Resolver-->>Agent: ToolAuthorizationError
    end
    Resolver-->>Agent: tool result
  end

The resolution flow first checks if sandboxing is required for this tool call. If yes, it finds or creates a container with the appropriate scope, verifies the tool is permitted by the allow-list, and executes inside the container. The container’s lastActivityAt is updated after every tool execution to reset the idle timer.

Annotated Code Walkthrough

Walk through setting up a sandbox, executing a tool inside it, and handling lifecycle events:

// sandbox/config.ts — building sandbox configuration
import {
  DEFAULT_SANDBOX_WORKSPACE_ROOT,
  DEFAULT_SANDBOX_IMAGE,
  DEFAULT_SANDBOX_IDLE_HOURS,
  DEFAULT_SANDBOX_MAX_AGE_DAYS,
  DEFAULT_TOOL_ALLOW,
} from "./defaults.js";

export function buildSandboxConfig(
  userConfig: Partial<SandboxConfig>
): SandboxConfig {
  return {
    mode: userConfig.mode ?? "non-main",
    backend: userConfig.backend ?? "docker",
    workspaceRoot: userConfig.workspaceRoot ?? DEFAULT_SANDBOX_WORKSPACE_ROOT,
    dockerImage: userConfig.dockerImage ?? DEFAULT_SANDBOX_IMAGE,
    sshConfig: userConfig.sshConfig,
    browser: userConfig.browser ?? {
      cdpPort: DEFAULT_SANDBOX_BROWSER_CDP_PORT,
      autostartTimeoutMs: DEFAULT_SANDBOX_BROWSER_AUTOSTART_TIMEOUT_MS,
    },
    toolPolicies: userConfig.toolPolicies ?? DEFAULT_TOOL_ALLOW.map(
      tool => ({ tool, allow: true })
    ),
  };
}

// sandbox/docker-backend.ts — container creation
async function createContainer(
  config: SandboxConfig,
  agentId: string,
  scope: SandboxContext["scope"]
): Promise<SandboxContext> {
  const containerName = `openclaw-${scope}-${agentId}-${Date.now()}`;

  const mounts: WorkspaceMount[] = [
    {
      hostPath: path.join(config.workspaceRoot!, agentId),
      containerPath: "/agent",
      readOnly: false,
    },
    {
      hostPath: process.cwd(),
      containerPath: "/workspace",
      readOnly: true,  // User workspace is read-only by default
    },
  ];

  const dockerArgs = [
    "run", "-d",
    "--name", containerName,
    ...mounts.flatMap(m => [
      "-v", `${m.hostPath}:${m.containerPath}:${m.readOnly ? "ro" : "rw"}`,
    ]),
    ...(config.browser ? ["-p", `${config.browser.cdpPort}:9222`] : []),
    config.dockerImage!,
    "sleep", "infinity",  // Keep container alive
  ];

  await exec("docker", dockerArgs);

  return {
    containerName,
    workspaceMounts: mounts,
    dockerConfig: { image: config.dockerImage! },
    browserBridgeUrls: config.browser ? {
      http: `http://localhost:${config.browser.cdpPort}`,
      ws: `ws://localhost:${config.browser.cdpPort}`,
    } : undefined,
    scope,
    createdAt: new Date(),
    lastActivityAt: new Date(),
  };
}

// sandbox/executor.ts — tool execution inside container
async function executeInSandbox(
  ctx: SandboxContext,
  toolName: string,
  args: unknown,
  toolPolicies: ToolPolicy[]
): Promise<ToolResult> {
  // Check tool policy
  const policy = toolPolicies.find(p => p.tool === toolName);
  if (policy && !policy.allow) {
    return {
      content: `Tool "${toolName}" is not permitted in this sandbox`,
      isError: true,
      errorCode: 403,
    };
  }

  // Execute inside container
  const result = await exec("docker", [
    "exec", "-w", "/workspace",
    ctx.containerName,
    "openclaw-tool", toolName, JSON.stringify(args),
  ]);

  // Update activity timestamp
  ctx.lastActivityAt = new Date();

  return { content: result.stdout, isError: result.exitCode !== 0 };
}

// sandbox/lifecycle.ts — idle and age monitoring
async function monitorContainers(
  containers: Map<string, SandboxContext>
): Promise<void> {
  const now = new Date();

  for (const [id, ctx] of containers) {
    const idleMs = now.getTime() - ctx.lastActivityAt.getTime();
    const ageMs = now.getTime() - ctx.createdAt.getTime();

    const idleLimitMs = DEFAULT_SANDBOX_IDLE_HOURS * 3600_000;
    const ageLimitMs = DEFAULT_SANDBOX_MAX_AGE_DAYS * 86400_000;

    if (idleMs > idleLimitMs || ageMs > ageLimitMs) {
      console.log(`Removing sandbox ${ctx.containerName}: ` +
        (idleMs > idleLimitMs ? "idle timeout" : "max age exceeded"));
      await exec("docker", ["rm", "-f", ctx.containerName]);
      containers.delete(id);
    }
  }
}

Edge Cases & Error Handling

Configuration

Runtime Info

The sandbox-info.ts module provides a read-only view of the current sandbox state for debugging and monitoring:

// sandbox/sandbox-info.ts
export function getSandboxInfo(ctx: SandboxContext | null): SandboxInfo {
  if (!ctx) return { active: false };
  return {
    active: true,
    containerName: ctx.containerName,
    scope: ctx.scope,
    backend: ctx.dockerConfig ? "docker" : "ssh",
    mounts: ctx.workspaceMounts.map(m => ({
      host: m.hostPath,
      container: m.containerPath,
      mode: m.readOnly ? "ro" : "rw",
    })),
    browser: ctx.browserBridgeUrls ?? null,
    uptime: Date.now() - ctx.createdAt.getTime(),
    idleSince: Date.now() - ctx.lastActivityAt.getTime(),
  };
}

Related Topics

See also:

• Tool Use overview — parent module covering all tool-related subsystems
• Function Calling — how tool calls are validated, repaired, and dispatched
• MCP Bridge — how external MCP tool servers connect to the runtime

Directory Map

src/agents/tools/
├── sandbox/
│   ├── types.ts                    ← SandboxConfig, SandboxContext, WorkspaceMount types
│   ├── defaults.ts                 ← Default constants (image, ports, timeouts, tool allow-list)
│   ├── config.ts                   ← Config builder with default fallbacks
│   ├── docker-backend.ts           ← Docker container creation and management
│   ├── ssh-backend.ts              ← SSH session creation and management
│   ├── executor.ts                 ← Tool execution inside sandbox (policy check + docker exec)
│   ├── lifecycle.ts                ← Idle/age monitoring and cleanup
│   └── sandbox-info.ts             ← Read-only runtime info for debugging
├── sessions-spawn-tool.ts          ← Agent spawning with ACP sandbox inheritance
└── tool-runtime.helpers.ts         ← Sandbox integration in tool runtime init