How ClosedClaw's Sandbox Execution Environment Isolates Tool Operations

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:

{
  "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:

{
  "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:

{
  "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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}