Sandbox Isolation

Every tool execution in Clawpy runs inside a Docker sandbox — an isolated container with constrained resources, limited network access, and a read-only root filesystem. This ensures that even if an agent makes a catastrophic mistake, the blast radius is contained.

Sandbox Architecture

Host System
  └── Clawpy Backend
        └── SandboxExecutor
              ├── Container: agent_cto_session_abc123
              │     ├── Memory limit: 512MB
              │     ├── CPU limit: 1.0 cores
              │     ├── Network: bridge (constrained)
              │     └── Filesystem: read-only root, /workspace writable
              │
              └── Container: heartbeat_worker
                    ├── Memory limit: 256MB
                    ├── CPU limit: 0.5 cores
                    ├── Network: bridge
                    └── Filesystem: read-write (for task execution)

Configuration

Each sandbox is configured via SandboxConfig:

Parameter	Default (Agent)	Default (Heartbeat)	Purpose
`memory`	`512m`	`256m`	Container memory limit
`cpus`	`1.0`	`0.5`	CPU core allocation
`network`	`none`	`bridge`	Network access policy
`read_only_root`	`true`	`false`	Filesystem immutability
`scope`	`session`	`agent`	Container lifecycle
`timeout`	`120s`	`120s`	Maximum execution time

Scoping Strategies

Session-scoped (`scope: "session"`)

One container per user session. Destroyed when the session ends. Used for interactive agent work.

Agent-scoped (`scope: "agent"`)

One container per agent. Persists across sessions. Used for background tasks like Heartbeat where the container needs to survive session boundaries.

Stale Container Pruning

The Heartbeat Protocol runs a daily cleanup job that removes containers idle for more than 24 hours:

# Runs every 24 hours via APScheduler
def _prune_sandboxes(self):
    from core.sandbox.docker import prune_stale_containers
    removed = prune_stale_containers(max_age_hours=24)

This prevents orphaned containers from consuming host resources indefinitely.

Ephemeral Token Management

Sandbox containers may need temporary API credentials (e.g., for git pull, npm install). Clawpy manages these through the SecretsManager with ephemeral tokens that auto-expire:

Tokens are injected into containers as environment variables
Expired tokens are purged every 5 minutes by the Heartbeat reaper
No credentials are persisted to disk inside the container

Defence in Depth

Sandbox Isolation is one layer of a three-layer security stack:

Layer	System	Protection
Input	Guardian Scanner	Blocks malicious input before it reaches the agent
Execution	Intent Cipher	Ensures tool calls match genuine user intent
Runtime	Sandbox Isolation	Contains blast radius of any tool execution

Together, these three systems ensure that an attack must compromise all three layers simultaneously to cause damage — a significantly higher bar than any single security control.