Sandboxing AI Agents: Container Isolation Explained

Sandboxing AI agents means running them inside an isolated environment — typically a container — where they cannot access the host filesystem, network, or processes unless explicitly permitted. SafeClaw by Authensor adds a second layer of defense inside the sandbox: even within the container, every agent action is evaluated against a deny-by-default policy before execution, catching actions that container isolation alone would miss, such as accessing sensitive files within the mounted workspace.

Quick Start

npx @authensor/safeclaw

Why Containers Alone Are Not Enough

Containers (Docker, Podman) provide OS-level isolation: separate filesystem, network namespace, and process tree. But AI agents typically need access to a workspace directory mounted into the container. Once inside that mount, a container provides no granularity — the agent can read, write, or delete any file in the mounted path.

SafeClaw fills this gap by enforcing file-level, command-level, and network-level policies within the container.

Docker Sandbox Configuration

Minimal Secure Container

FROM node:20-slim

Non-root user
RUN useradd -m -s /bin/bash agent
USER agent
WORKDIR /home/agent/workspace

Install SafeClaw
RUN npx @authensor/safeclaw

COPY .safeclaw/ /home/agent/.safeclaw/

Docker Run with Security Options

docker run \
  --read-only \
  --tmpfs /tmp:size=100M \
  --tmpfs /home/agent/.cache:size=50M \
  --memory=512m \
  --cpus=1 \
  --network=none \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  -v $(pwd)/src:/home/agent/workspace/src:ro \
  -v $(pwd)/.safeclaw:/home/agent/.safeclaw:ro \
  ai-agent-sandbox

This configuration enforces:

| Flag | Protection |
|---|---|
| --read-only | Root filesystem is immutable |
| --tmpfs /tmp | Temporary writes only in RAM, size-limited |
| --memory=512m | Prevents memory exhaustion |
| --cpus=1 | Prevents CPU monopolization |
| --network=none | No network access |
| --cap-drop=ALL | No Linux capabilities |
| --no-new-privileges | Cannot escalate via setuid/setgid |
| :ro mount | Workspace is read-only at OS level |

Podman Alternative

Podman runs containers rootless by default, adding another isolation layer:

podman run \
  --read-only \
  --tmpfs /tmp:size=100M \
  --memory=512m \
  --cpus=1 \
  --network=none \
  --cap-drop=ALL \
  --userns=keep-id \
  -v $(pwd)/src:/workspace/src:ro \
  ai-agent-sandbox

The --userns=keep-id flag maps the container user to the host user, preventing UID mismatch issues with mounted volumes.

SafeClaw Policy Inside the Container

Even with container isolation, SafeClaw enforces granular controls within the mounted workspace:

version: "1.0"
description: "Container sandbox policy"

rules:
  # Allow reads within workspace
  - action: file.read
    path: "/home/agent/workspace/src/**"
    effect: allow
    reason: "Read source files"

# Block reads to config files even within workspace
  - action: file.read
    path: "*/.env"
    effect: deny
    reason: "Block env files even inside sandbox"

- action: file.read
    path: "*/config/secrets."
    effect: deny
    reason: "Block secret configs"

# Controlled shell execution
  - action: shell.execute
    command: "npm test"
    effect: allow

- action: shell.execute
    command: "npm run build"
    effect: allow

- action: shell.execute
    command: "*"
    effect: deny
    reason: "Block arbitrary shell commands"

- action: "*"
    effect: deny
    reason: "Sandbox baseline: deny all"

Resource Limits as Policy

Combine container resource limits with SafeClaw budget policies:

budgets:
  - scope: agent
    limit: "$5.00"
    period: hourly
    action: deny
    reason: "Sandbox agent hourly spend cap"

This prevents a sandboxed agent from accumulating costs even if it has network access for LLM API calls.

Docker Compose for Development

# docker-compose.yaml
version: "3.8"

services:
  ai-agent:
    build: .
    read_only: true
    tmpfs:
      - /tmp:size=100M
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
    networks:
      - restricted
    volumes:
      - ./src:/workspace/src:ro
      - ./.safeclaw:/home/agent/.safeclaw:ro
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges

networks:
  restricted:
    internal: true  # No external access

Defense in Depth

Container sandboxing + SafeClaw provides two independent enforcement layers:

1. Container layer — OS-level isolation (filesystem, network, processes, resources)
2. SafeClaw layer — action-level isolation (file paths, commands, domains, budgets)

Why SafeClaw

• 446 tests ensure policy enforcement works correctly inside container environments
• Deny-by-default catches anything container isolation misses within mounted volumes
• Sub-millisecond evaluation adds no perceptible overhead inside containers
• Hash-chained audit trail works inside containers and can be exported via mounted volumes
• Works with Claude AND OpenAI — container + policy isolation applies to any LLM provider
• MIT licensed — include in your container images without licensing constraints

See Also

• Container Isolation for AI Agents: Docker vs Podman vs Firecracker
• Filesystem Isolation for AI Agents: Beyond Chroot
• Process Isolation for AI Agents: Preventing Privilege Escalation
• Zero Trust Architecture for AI Agents