Sandbox Guide

CortexPrism provides sandboxed code execution using Docker containers (with subprocess fallback). This guide covers usage, configuration, and security.

Overview

The sandbox system allows agents to execute code safely in isolated environments with resource constraints. Code runs in ephemeral containers that are destroyed after execution.

How It Works

cortex run script.py                 # Auto-detect language, run in sandbox
cortex run script.py --no-sandbox    # Skip sandbox, run as subprocess
cortex run script.py --fix           # Enable auto-fix on failure

Docker Sandbox

When Docker is available, containers are created with strict resource limits:

Constraint	Value
Network	`--network=none` (no external access)
Memory	256MB limit
CPU	0.5 cores
Process limit	64 PIDs
Security	`no-new-privileges`
Timeout	30 seconds
Max output	64KB

Supported Languages

Language	Extension	Docker Image	Interpreter
Python	`.py`	`python:3.12-slim`	`python3`
JavaScript	`.js`	`node:22-slim`	`node`
TypeScript	`.ts`	`node:22-slim`	`npx tsx`
Bash	`.sh`	`ubuntu:24.04`	`bash`
Ruby	`.rb`	`ruby:3.3-slim`	`ruby`
Go	`.go`	`golang:1.23-bookworm`	`go run`
Rust	`.rs`	`rust:1.78-slim`	`rustc -o /tmp/out && /tmp/out`

Subprocess Fallback

When docker info fails (Docker not installed or daemon not running), the sandbox falls back to subprocess mode. The code runs directly on the host machine with the same resource limits applied at the process level.

Auto-Fix Loop

When --fix is enabled, the system can automatically fix broken code:

runInSandbox(code)
  → exit != 0?
     → LLM receives: "Fix this error: <stderr>\n\nCode:\n<code>"
     → LLM returns fixed code
     → runInSandbox(fixedCode)
     → repeat up to maxRounds (default: 4)

# Enable auto-fix
cortex run buggy-code.py --fix

# Increase max fix attempts
cortex run complex.js --fix --max-fix 8

Security Considerations

Docker sandbox has no network access (--network=none)
Memory and CPU are strictly limited to prevent resource exhaustion
Containers are ephemeral — no data persists after execution
The no-new-privileges security flag prevents privilege escalation
Output is capped at 64KB to prevent log flooding

Configuration

The sandbox can be configured through environment variables:

Variable	Description	Default
`CORTEX_SANDBOX_TIMEOUT`	Execution timeout in seconds	`30`
`CORTEX_SANDBOX_MEMORY`	Memory limit in MB	`256`
`CORTEX_SANDBOX_MAX_OUTPUT`	Output cap in KB	`64`

Best Practices

Always use the sandbox for untrusted code — avoid --no-sandbox unless necessary
Enable auto-fix during development to iterate faster
Keep scripts simple — the sandbox has limited memory and no network
Use Python for data analysis — the Python sandbox includes pip for package installation