# How ClosedClaw's Sandbox Execution Environment Isolates Tool Operations

> Discover how ClosedClaw's Docker sandbox secures tool operations with containerization, read-only filesystems, and network lockdown. Prevent host compromise effectively.

- Repository: [aSafeLobotomy/closedclaw](https://github.com/asafelobotomy/closedclaw)
- Tags: internals
- Published: 2026-02-25

---

**ClosedClaw enforces isolation by running every tool inside a Docker-based sandbox execution environment that employs containerization, read-only filesystems, network lockdown, and Linux capability dropping to prevent host compromise.**

The ClosedClaw repository implements a defense-in-depth **sandbox execution environment** designed to contain potentially dangerous tool operations—such as arbitrary code execution, file system modifications, and network requests—within strictly controlled boundaries. By leveraging Docker containers with hardened security profiles, the system ensures that even if a tool or AI model is compromised, the blast radius remains limited to the isolated container.

## Core Isolation Mechanisms in the Sandbox Execution Environment

### Containerization and Filesystem Isolation

At the heart of the **sandbox execution environment** lies per-container isolation managed through the `ensureSandboxContainer` function in **[src/agents/sandbox/docker.ts]**. Each sandboxed tool runs inside its own Docker container (or a shared one per session/agent), ensuring the host OS and other containers remain inaccessible.

The filesystem is hardened through multiple layers:

- **Read-only root filesystem**: The `buildSandboxCreateArgs` function injects `--read-only` into the Docker run command, preventing modification of system binaries or libraries.
- **Tmpfs and limited bind-mounts**: Only explicitly configured directories are bind-mounted via `--volume` flags. The host file system remains invisible unless explicitly exposed through `workspaceAccess` settings (`none`, `ro`, or `rw`).
- **Isolated workspace**: The sandbox maintains its own workspace under `~/.ClosedClaw/sandboxes/`, separate from the host agent workspace.

### Network and Capability Restrictions

The **sandbox execution environment** aggressively restricts network access and privileges to prevent data exfiltration and privilege escalation:

- **Network lockdown**: By default, `docker.network="none"` is defined in **[src/agents/sandbox/constants.ts]** and applied via `--network none` in `buildSandboxCreateArgs`. This blocks all external network access, stopping malicious downloads or data leaks.
- **Capability dropping**: All Linux capabilities are removed using `--cap-drop ALL`, preventing privileged operations such as mounting devices, modifying kernel parameters, or accessing raw network sockets.
- **User namespace isolation**: When configured, containers run as unprivileged users via `--user` flags, preventing escalation to host root even if the container is compromised.

### Security Profiles and Namespace Isolation

For environments requiring additional hardening, the **sandbox execution environment** supports **Seccomp** and **AppArmor** profiles:

- **Seccomp profiles**: The `buildSandboxCreateArgs` function accepts `--security-opt seccomp=` parameters to enforce syscall whitelisting, providing deny-by-default protection against dangerous kernel calls.
- **AppArmor profiles**: Similarly, `--security-opt apparmor=` applies mandatory access control policies to restrict file access and capabilities beyond standard Docker isolation.

These profiles are optional but recommended for high-risk tool operations.

## Configuration-Driven Isolation Policies

### Workspace Access Controls

The **sandbox execution environment** exposes granular workspace controls through the `workspaceAccess` configuration parameter, defined in **[src/agents/sandbox/config.ts]** and enforced during container creation:

- **`none`**: No host workspace access; the tool operates solely within the isolated sandbox directory.
- **`ro`**: Read-only bind-mount of the host workspace, preventing modifications to host files.
- **`rw`**: Read-write access for trusted workflows requiring file modifications.

These controls are implemented via `--volume` flags in `buildSandboxCreateArgs` in **[src/agents/sandbox/docker.ts]**.

### Scope and Lifecycle Management

Isolation boundaries are further defined by sandbox scope, managed in **[src/agents/sandbox/shared.ts]** through `resolveSandboxScopeKey`:

- **`session`**: One container per chat session, isolating conversations from each other.
- **`agent`**: Shared container per agent configuration, balancing isolation with resource efficiency.
- **`shared`**: Global container across all agents (least isolated, not recommended for untrusted code).

The `maybePruneSandboxes` function in **[src/agents/sandbox/prune.ts]** periodically removes idle containers based on `idleHours` and `maxAgeDays` settings, preventing stale containers from persisting with outdated security configurations.

## Runtime Enforcement and Integrity Checks

### Configuration Hash Validation

To prevent security degradation, the **sandbox execution environment** implements immutable configuration tracking via `ClosedClaw.configHash` labels on containers. The `readContainerConfigHash` and `ensureSandboxContainer` functions in **[src/agents/sandbox/docker.ts]** perform the following:

1. Calculate a hash of the current sandbox configuration.
2. Compare it against the `ClosedClaw.configHash` label on the existing container.
3. If mismatched, log a warning: *"Sandbox config changed for ClosedClaw-sandbox-{id} (recently used). Recreate to apply: ClosedClaw sandbox recreate --session {id}"*

This ensures containers never run with out-of-date security settings.

### Tool Policy Enforcement

Even within an isolated container, the **sandbox execution environment** enforces tool-specific policies through `resolveSandboxToolPolicyForAgent` in **[src/agents/sandbox/tool-policy.ts]**. Each sandbox configuration includes a `toolPolicy.allow` list; if a tool is not explicitly allowed, the execution request is rejected before reaching the container.

Additionally, `resolveSandboxRuntimeStatus` in **[src/agents/sandbox/runtime-status.ts]** determines whether sandboxing is active for a given session. If `agents.defaults.sandbox.mode="off"` is configured, tools run on the host—but only after explicit administrative override.

## Practical Configuration Examples

### Enabling Strict Sandbox Isolation

To enforce maximum isolation for all agents, configure the **sandbox execution environment** with read-only filesystems, no network access, and session-scoped containers:

```json5
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "scope": "session",
        "workspaceAccess": "none",
        "docker": {
          "readOnlyRoot": true,
          "network": "none",
          "capDrop": ["ALL"]
        }
      }
    }
  }
}

```

This configuration utilizes `buildSandboxCreateArgs` in **[src/agents/sandbox/docker.ts]** to inject `--read-only`, `--network none`, and `--cap-drop ALL` flags.

### Executing Commands in the Sandbox

To run a tool within the isolated **sandbox execution environment**, specify the `host` parameter as `sandbox`:

```json
{
  "tool": "exec",
  "command": "git rev-parse HEAD",
  "host": "sandbox"
}

```

The runtime resolves the session’s sandbox container via `ensureSandboxContainer`, mounts the isolated workspace, and executes `sh -lc "git rev-parse HEAD"` inside the container with all security restrictions active.

### Allowing Controlled Workspace Access

For workflows requiring file modifications, temporarily elevate `workspaceAccess` while maintaining other isolation boundaries:

```json5
{
  "agents": {
    "defaults": {
      "sandbox": {
        "workspaceAccess": "rw",
        "docker": {
          "network": "none",
          "readOnlyRoot": true
        }
      }
    }
  }
}

```

After applying this configuration, `ensureSandboxContainer` creates containers that bind-mount the host workspace at `/workspace` with read-write permissions, while maintaining the read-only root filesystem and network isolation.

## Summary

- **Containerization**: ClosedClaw’s **sandbox execution environment** isolates each tool operation within Docker containers using `ensureSandboxContainer` in **[src/agents/sandbox/docker.ts]**, preventing direct host access.
- **Filesystem Lockdown**: Read-only root filesystems (`--read-only`), limited bind-mounts, and configurable `workspaceAccess` levels (`none`, `ro`, `rw`) enforce strict data boundaries.
- **Network and Privilege Restrictions**: Default `network="none"` and `capDrop=["ALL"]` eliminate external connectivity and privileged operations, stopping data exfiltration and kernel manipulation.
- **Integrity Enforcement**: Configuration hash tracking via `ClosedClaw.configHash` labels ensures containers are recreated when security settings change, preventing stale configurations.
- **Policy Controls**: Tool-specific policies and runtime status checks in **[src/agents/sandbox/tool-policy.ts]** and **[src/agents/sandbox/runtime-status.ts]** provide additional execution gates beyond container boundaries.

## Frequently Asked Questions

### What happens if the sandbox configuration changes while a container is running?

If the sandbox configuration is modified, the `ensureSandboxContainer` function in **[src/agents/sandbox/docker.ts]** detects a hash mismatch between the current configuration and the `ClosedClaw.configHash` label on the existing container. Rather than silently applying changes to a running container, the system logs a warning indicating that the container is stale and provides a command (`ClosedClaw sandbox recreate --session {id}`) to recreate the container with updated security settings. This prevents containers from running with outdated isolation policies.

### Can I disable sandboxing for specific tools or agents?

Yes, but only through explicit administrative override. The `resolveSandboxRuntimeStatus` function in **[src/agents/sandbox/runtime-status.ts]** checks the `agents.defaults.sandbox.mode` setting. If set to `"off"`, tools run directly on the host without containerization. Additionally, individual tools can specify a `host` parameter (e.g., `"gateway"` or `"node"`) to bypass the sandbox, though this typically triggers additional approval workflows. By default, `mode` is set to `"all"`, enforcing sandboxing for every tool execution.

### How does the sandbox handle file system access for tools that need to modify project files?

The **sandbox execution environment** provides granular workspace controls through the `workspaceAccess` configuration parameter, managed in **[src/agents/sandbox/config.ts]** and enforced during container creation in **[src/agents/sandbox/docker.ts]**. When set to `"rw"`, the `buildSandboxCreateArgs` function includes a `--volume` mount that binds the host workspace to `/workspace` with read-write permissions inside the container. When set to `"ro"`, the mount is read-only, and when set to `"none"`, no host workspace is visible. This allows specific workflows to modify files while maintaining other isolation boundaries like read-only root filesystems and network restrictions.

### What Linux security features does the sandbox use beyond standard Docker isolation?

Beyond standard containerization, ClosedClaw’s **sandbox execution environment** leverages several advanced Linux security mechanisms configured in `buildSandboxCreateArgs` within **[src/agents/sandbox/docker.ts]**. These include **Seccomp** profiles (`--security-opt seccomp=`) to whitelist permitted syscalls and **AppArmor** profiles (`--security-opt apparmor=`) for mandatory access control. Additionally, the implementation drops all Linux capabilities using `--cap-drop ALL`, preventing privileged operations like kernel module loading or raw socket access. When combined with user namespace remapping (`--user`) and read-only root filesystems (`--read-only`), these features provide defense-in-depth isolation that exceeds default Docker configurations.