Sandboxing AI Agents

Sandboxing isolates your AI agent from the rest of your system, limiting what it can read, write, and communicate with. This defense layer ensures that even a compromised or misbehaving agent cannot damage your system or leak data.

Security8 min read

Why Sandboxing Matters

AI agents are non-deterministic. Unexpected inputs, prompt injections, or bugs can cause an agent to take unintended actions. Without a sandbox:

  • An agent reading a malicious file could be instructed to delete system files
  • A code-execution tool could give the agent access to your entire system
  • Sensitive files outside the working directory could be exfiltrated

A sandbox provides a hard boundary regardless of the agent's instructions.

Docker-Based Sandboxing

Docker is the recommended sandboxing approach for most deployments. OpenClaw can run entirely within a container with strict restrictions:

Read-Only Filesystem

# Mount input as read-only, output as writable
docker run \
  --read-only \
  -v /host/input:/data/input:ro \
  -v /host/output:/data/output:rw \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  openclaw/openclaw:latest \
  openclaw run "Analyze files in /data/input"

Network Isolation

# No network access (fully air-gapped — use with local Ollama)
docker run --network none \
  -v /host/input:/data:ro \
  openclaw/openclaw:latest run "Summarize this document"

# Restricted network: only allow specific API endpoints
docker network create --driver bridge --internal openclaw-net

# Add DNS resolution only for allowed hosts
# (Use a custom DNS or firewall rules outside the container)

Resource Limits

# Limit CPU and memory
docker run \
  --memory="2g" \
  --memory-swap="2g" \
  --cpus="1.5" \
  --pids-limit=100 \
  openclaw/openclaw:latest run "your task"

User Namespace Remapping

# Run as non-root user inside container
docker run \
  --user 1000:1000 \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  openclaw/openclaw:latest run "your task"

OpenClaw Sandbox Configuration

OpenClaw has a built-in sandbox configuration that restricts agent behavior at the application level:

# config.yaml
sandbox:
  enabled: true
  filesystem:
    mode: readonly          # readonly | restricted | full
    read_paths:
      - "/data/input"
    write_paths:
      - "/data/output"
    blocked_paths:
      - "/etc"
      - "/root"
      - "/home"
      - "/sys"
      - "/proc"
  network:
    mode: restricted        # none | restricted | full
    allowlist:
      - "api.openai.com"
      - "api.anthropic.com"
    block_private_ips: true # block 10.x, 172.16.x, 192.168.x
  process:
    allow_execution: false  # block shell command execution
    max_memory_mb: 512
    timeout_seconds: 120

Filesystem Path Restrictions

Control exactly which paths the agent can read and write:

sandbox:
  filesystem:
    # Allowlist approach (safest)
    read_paths:
      - "/workspace/src"
      - "/workspace/docs"
    write_paths:
      - "/workspace/output"
      - "/tmp/openclaw"

    # Additional blocklist (belt-and-suspenders)
    blocked_paths:
      - "/etc/passwd"
      - "/etc/shadow"
      - "/root/.ssh"
      - "/home/*/.ssh"
Allowlist over Blocklist: Always prefer an allowlist (specify what IS allowed) rather than a blocklist (specify what is NOT allowed). New directories could be created that bypass a blocklist.

VM-Based Isolation

For maximum isolation, run agents in a lightweight virtual machine. This provides kernel-level separation:

Firecracker MicroVMs

# Firecracker provides sub-second VM startup with full kernel isolation
# Used by AWS Lambda under the hood

# Install and configure Firecracker
curl -fsSL https://github.com/firecracker-microvm/firecracker/releases/download/v1.5.0/firecracker-v1.5.0-x86_64.tgz | tar -xz

# Create a minimal rootfs with OpenClaw installed
# Then start the microVM for each agent run

Firecracker is recommended for multi-tenant environments where you run agents on behalf of different users.

Logging Sandbox Activity

All sandbox violations should be logged for security analysis:

audit:
  enabled: true
  log_file: "/var/log/openclaw/sandbox.json"
  log_sandbox_violations: true
  categories:
    - filesystem_block
    - network_block
    - process_block
// Example sandbox violation log entry
{
  "timestamp": "2026-03-13T10:23:45Z",
  "event": "filesystem_block",
  "severity": "warning",
  "task_id": "task-abc123",
  "attempted_path": "/etc/passwd",
  "action": "read",
  "reason": "path_not_in_allowlist"
}

What's Next

Defense in Depth with Sandboxing

Sandboxing is most effective when applied in layers. A process-level sandbox limits what system calls the agent process can make. A filesystem sandbox limits which paths it can read and write. A network sandbox limits which hosts it can contact. An API sandbox controls which tools and operations it can invoke. Each layer provides independent protection — if an attacker bypasses the process sandbox, the filesystem sandbox may still prevent data exfiltration. This defense-in-depth approach means no single sandbox escape gives full access.

For agents executing user-provided code or processing untrusted content, apply the strictest sandboxing available. Containerize the execution, restrict capabilities using Linux seccomp or container runtime policies, and run as an unprivileged user. Mount the filesystem read-only except for designated scratch space. Drop all network access unless the task explicitly requires it. These controls are inexpensive to apply and significantly limit the blast radius of a successful prompt injection or code injection attack.

Test your sandbox boundaries explicitly. Create synthetic test cases that attempt to read restricted files, contact blocked hosts, or execute restricted commands. Verify that each attempt fails with a permission error rather than silently succeeding. This proactive validation catches sandbox configuration mistakes before an attacker does. Include sandbox boundary tests in your CI pipeline so that future configuration changes don't inadvertently widen the sandbox without detection.

Monitoring Sandbox Activity

Enable detailed logging of sandbox boundary events — every filesystem access attempt, every network connection, every system call that is blocked by policy. This telemetry serves two purposes. First, it provides an audit trail of exactly what a sandboxed agent attempted, which is valuable for both debugging and security incident investigation. Second, a pattern of repeated blocked attempts at a specific resource can indicate that an agent is being manipulated to probe the sandbox boundary — an early warning of a potential prompt injection or jailbreak attempt in progress.