Sandbox Execution

Run Claude Code in completely isolated environments for safe experimentation, testing, or executing untrusted code.

Overview

Claude Code Templates supports three sandbox providers:

E2B - Cloud-based sandboxes with automatic cleanup
Docker - Local containerized environments
Cloudflare Workers - Serverless edge computing

E2B Cloud Sandboxes

E2B provides isolated cloud environments perfect for safe code execution without affecting your local machine.

Setup

Get E2B API Key

Set Environment Variable

export E2B_API_KEY=your_api_key_here
export ANTHROPIC_API_KEY=your_anthropic_key

Run Sandbox

npx claude-code-templates@latest --sandbox e2b --prompt "Create a React todo app"

Using E2B with Components

Install specific components before execution:

npx claude-code-templates@latest \
  --sandbox e2b \
  --agent react-expert,frontend-developer \
  --prompt "Build a responsive dashboard with charts"

The sandbox will:

Create an isolated E2B cloud environment
Install specified agents/commands/MCPs
Execute your prompt with Claude Code
Download all generated files to your local machine
Automatically clean up the sandbox

How It Works

The E2B launcher (e2b-launcher.py) handles the entire lifecycle:

# Executed automatically when you use --sandbox e2b
python e2b-launcher.py \
  "your prompt" \
  "--agent react-expert" \
  $E2B_API_KEY \
  $ANTHROPIC_API_KEY

Key Features:

Automatic timeout management - Extends sandbox lifetime during operations
Real-time streaming - See Claude Code output as it happens
File download - All generated files copied to sandbox-{id}/ directory
WebSocket retry logic - Handles connection issues gracefully
Progress indicators - Visual feedback during execution

Files are downloaded to a project directory named sandbox-{id} in your current working directory, preserving the full directory structure.

Environment Variables

Pass additional environment variables to the sandbox:

export E2B_API_KEY=your_key
export ANTHROPIC_API_KEY=your_key
export DATABASE_URL=postgres://...

npx claude-code-templates@latest \
  --sandbox e2b \
  --prompt "Set up database migrations"

The sandbox environment inherits:

ANTHROPIC_API_KEY (required)
E2B_API_KEY (required)
Custom environment variables you set

E2B sandboxes have a 10-15 minute timeout. The launcher automatically extends this to 15 minutes for long-running operations.

Monitoring Sandbox Execution

The E2B launcher provides real-time feedback:

☁️  EXECUTING CLAUDE CODE IN SECURE CLOUD SANDBOX
════════════════════════════════════════════════

    ⏳ Starting execution...
    🔒 Isolated E2B environment active
    📡 Streaming real-time output below:

────────────────────────────────────────────────
📝 LIVE OUTPUT:
────────────────────────────────────────────────

🎯 Claude Code started responding:

[Real-time output from Claude Code...]

Troubleshooting E2B

WebSocket Connection Failed

⚠️  WebSocket connection failed, retrying in 3 seconds...

This is usually caused by:

Network/firewall blocking WebSocket connections
Corporate proxy restrictions
Temporary E2B service issues

Solutions:

Try from a different network
Check firewall/proxy settings
Wait a few minutes and retry

No Files Generated If the sandbox completes but no files appear:

# The launcher searches for common file extensions
# Check the sandbox output for file paths
# Files are saved to: sandbox-{id}/

Docker Local Sandboxes

Run Claude Code in isolated Docker containers on your local machine.

Prerequisites

Install Docker

Download from docker.com

Start Docker Daemon

Ensure Docker Desktop is running or start the daemon:

# macOS/Windows: Launch Docker Desktop
# Linux:
sudo systemctl start docker

Set API Key

export ANTHROPIC_API_KEY=your_api_key

Running Docker Sandboxes

npx claude-code-templates@latest \
  --sandbox docker \
  --prompt "Create a Python FastAPI server"

First run:

🔨 Checking Docker image...
   📦 Building Docker image (this may take a few minutes)...

Subsequent runs:

🔨 Checking Docker image...
   ✅ Image already exists

Docker Architecture

The Docker launcher (docker-launcher.js) orchestrates:

Image build - Creates claude-sandbox image with Node.js and dependencies
Volume mounting - Maps ./output/ for file persistence
Environment injection - Passes ANTHROPIC_API_KEY securely
Container execution - Runs execute.js with your prompt
Cleanup - Removes container with --rm flag

// Executed automatically
node docker-launcher.js \
  "your prompt" \
  "--agent python-expert"

Output Directory

All files are saved to ./output/ in your current directory:

output/
├── main.py
├── requirements.txt
├── Dockerfile
└── README.md

The Docker container runs with --rm flag, so it’s automatically removed after execution. Only files in the mounted output/ directory persist.

Custom Docker Configuration

Modify the Dockerfile in components/sandbox/docker/Dockerfile:

FROM node:18-alpine

# Add system dependencies
RUN apk add --no-cache python3 py3-pip git

# Install Claude Code
RUN npm install -g claude-code

# Set working directory
WORKDIR /app

# Copy execution script
COPY execute.js /app/

CMD ["node", "execute.js"]

Cloudflare Workers Sandbox

Run Claude Code in serverless edge environments.

Setup Cloudflare Sandbox

npx claude-code-templates@latest \
  --sandbox cloudflare \
  --prompt "Create a serverless API"

This installs the Cloudflare sandbox components to .claude/sandbox/cloudflare/:

.claude/sandbox/cloudflare/
├── src/index.ts      # Main worker entry point
├── launcher.ts       # Local development launcher
├── monitor.ts        # Execution monitoring
├── wrangler.toml     # Cloudflare configuration
└── package.json      # Dependencies

Deploying to Cloudflare

Install Wrangler

npm install -g wrangler

Authenticate

wrangler login

Deploy Worker

cd .claude/sandbox/cloudflare
wrangler deploy

Local Development

cd .claude/sandbox/cloudflare
npm run dev

Access the worker at http://localhost:8787

Sandbox Comparison

Feature	E2B	Docker	Cloudflare
Environment	Cloud	Local	Edge
Setup Time	Instant	2-5 min (first build)	Moderate
Isolation	Complete	Complete	Sandboxed
File Access	Downloaded	Mounted volume	Limited
Internet	✅ Yes	✅ Yes	✅ Yes
Cleanup	Automatic	Automatic (container)	Manual
Cost	Pay per use	Free (local resources)	Free tier available
Best For	Quick experiments	Offline work	Serverless APIs

Security Considerations

Never run untrusted code outside a sandbox. Always use sandbox execution when:

Testing code from unknown sources
Experimenting with system-level operations
Running potentially destructive commands
Working with sensitive data in isolated environments

Sandbox Isolation

All sandbox providers offer:

Process isolation - Code runs in separate processes
Filesystem isolation - Limited access to host files
Network isolation - Controlled outbound connections
Resource limits - CPU, memory, and time constraints

API Key Security

API keys are passed securely:

# ✅ Good - Environment variables
export ANTHROPIC_API_KEY=sk-ant-...
export E2B_API_KEY=...

# ❌ Bad - Never hardcode keys
npx claude-code-templates --anthropic-api-key sk-ant-...  # Visible in process list

Advanced Usage

Batch Sandbox Execution

Run multiple prompts in sequence:

#!/bin/bash

prompts=(
  "Create a REST API with Express"
  "Add authentication middleware"
  "Write integration tests"
)

for prompt in "${prompts[@]}"; do
  npx claude-code-templates@latest \
    --sandbox e2b \
    --agent backend-developer \
    --prompt "$prompt"
done

Custom Sandbox Templates

Create your own E2B templates:

# e2b.toml
from = "ubuntu:22.04"

[exec]
cmd = "npm install -g claude-code"

Monitoring Long-Running Tasks

The E2B monitor provides progress updates:

# From e2b-launcher.py
def show_progress():
    progress_messages = [
        "⏳ Still processing...",
        "🔄 Claude Code is working on your request...",
        "⚙️  Analyzing requirements...",
        "🛠️  Building solution...",
    ]

Examples

Safe Code Experimentation

npx claude-code-templates@latest \
  --sandbox e2b \
  --prompt "Experiment with different sorting algorithms and benchmark them"

Multi-Component Project

npx claude-code-templates@latest \
  --sandbox e2b \
  --agent fullstack-developer,database-expert \
  --mcp postgresql \
  --prompt "Create a blog platform with user authentication"

Testing Framework

npx claude-code-templates@latest \
  --sandbox docker \
  --agent testing-specialist \
  --prompt "Set up Jest with React Testing Library and write component tests"

Get Started

Core Concepts

Guides

Tools

Advanced

​Sandbox Execution

​Overview

​E2B Cloud Sandboxes

​Setup

​Using E2B with Components

​How It Works

​Environment Variables

​Monitoring Sandbox Execution

​Troubleshooting E2B

​Docker Local Sandboxes

​Prerequisites

​Running Docker Sandboxes

​Docker Architecture

​Output Directory

​Custom Docker Configuration

​Cloudflare Workers Sandbox

​Setup Cloudflare Sandbox

​Deploying to Cloudflare

​Local Development

​Sandbox Comparison

​Security Considerations

​Sandbox Isolation

​API Key Security

​Advanced Usage

​Batch Sandbox Execution

​Custom Sandbox Templates

​Monitoring Long-Running Tasks

​Examples

​Safe Code Experimentation

​Multi-Component Project

​Testing Framework

​Next Steps

Session Sharing

Remote Access

Build docs developers (and LLMs) love

Sandbox Execution

Overview

E2B Cloud Sandboxes

Setup

Using E2B with Components

How It Works

Environment Variables

Monitoring Sandbox Execution

Troubleshooting E2B

Docker Local Sandboxes

Prerequisites

Running Docker Sandboxes

Docker Architecture

Output Directory

Custom Docker Configuration

Cloudflare Workers Sandbox

Setup Cloudflare Sandbox

Deploying to Cloudflare

Local Development

Sandbox Comparison

Security Considerations

Sandbox Isolation

API Key Security

Advanced Usage

Batch Sandbox Execution

Custom Sandbox Templates

Monitoring Long-Running Tasks

Examples

Safe Code Experimentation

Multi-Component Project

Testing Framework

Next Steps