Autonomous Claude Sandbox Skill

Deploy Claude Code on Cloudflare Sandbox containers for autonomous AI task execution.

When to Use This Skill

Activate when you see these patterns:

Setup & Deployment:

• "Setup autonomous claude sandbox"
• "Deploy claude on cloudflare"
• "Set up Claude Code on Cloudflare containers"

Task Execution:

• "Execute task in sandbox"
• "Run this in the sandbox"
• "Delegate to sandbox"
• "Send to autonomous claude"
• "Run claude code autonomously"

Workflow Routing

Route to the appropriate workflow based on the request:

Setup & Operations:

• Set up new Cloudflare Sandbox deployment → Workflows/Setup.md
• Deploy/update existing deployment → Workflows/Deploy.md
• Troubleshoot issues → Workflows/Troubleshoot.md
• Upgrade SDK or dependencies → Workflows/Upgrade.md
• Monitor deployment health → Workflows/Monitor.md

Task Execution:

• Execute a task in the sandbox → Workflows/Execute.md

Deterministic Tools

These scripts output JSON and use proper exit codes for AI agent consumption.

Example: Execute Task

./Tools/execute-task.sh https://my-worker.workers.dev my-auth-token "Write a hello world script" | jq .

Output:

{
  "success": true,
  "taskId": "a1b2c3d4-...",
  "stdout": "Created hello.py with print('Hello, World!')",
  "execution_time_ms": 8500
}

Example: Check Prerequisites

./Tools/check-prerequisites.sh | jq .

Output:

{
  "success": true,
  "checks": {
    "node": { "installed": true, "version": "20.10.0", "meets_requirement": true },
    "docker": { "installed": true, "running": true },
    "wrangler": { "installed": true, "authenticated": true }
  },
  "issues": []
}

Example: Validate Config

./Tools/validate-config.sh /path/to/project | jq .

Example: Test Deployment

./Tools/test-deployment.sh https://my-worker.workers.dev my-auth-token | jq .

Quick Start

Prerequisites

• Cloudflare account with Workers Paid plan ($5/month)
• Docker Desktop running locally
• Node.js 18+
• Claude MAX subscription

Installation

# Clone reference implementation
git clone https://github.com/WellDunDun/claude-code-sandbox.git
cd claude-code-sandbox
npm install

# Authenticate with Cloudflare
npx wrangler login

# Create R2 bucket
npx wrangler r2 bucket create claude-results

# Set secrets
claude setup-token
npx wrangler secret put CLAUDE_CODE_OAUTH_TOKEN

openssl rand -hex 32
npx wrangler secret put SERVER_AUTH_TOKEN

# Configure and deploy
# Edit wrangler.jsonc with your account_id
npm run deploy

Test

# Health check
curl https://YOUR-WORKER.workers.dev/health

# Execute task
curl -X POST https://YOUR-WORKER.workers.dev/execute \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task": "What is 2 + 2?"}'

API Reference

Formal specification of the Cloudflare Sandbox Worker API endpoints.

GET /health

Health check endpoint. No authentication required.

Request:

curl https://YOUR-WORKER.workers.dev/health

Response (200 OK):

{
  "status": "healthy",
  "platform": "cloudflare_sandboxes",
  "auth_method": "claude_subscription_setup_token"
}

POST /execute

Execute a Claude Code task in an isolated sandbox container.

Headers:

Request Body:

{
  "task": "string",      // Required: Task description for Claude
  "timeout": 300000      // Optional: Timeout in ms (default: 300000)
}

Response (200 OK):

{
  "taskId": "uuid",
  "success": true,
  "stdout": "Task output...",
  "stderr": "",
  "output": "Task output..."
}

Error Responses:

Example:

curl -X POST https://YOUR-WORKER.workers.dev/execute \
  -H "Authorization: Bearer YOUR_SERVER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task": "What is 2 + 2?", "timeout": 60000}'

GET /tasks/:taskId/result

Retrieve stored task results from R2.

Headers:

Response (200 OK):

{
  "taskId": "uuid",
  "success": true,
  "stdout": "...",
  "stderr": "...",
  "timestamp": "2024-01-28T00:00:00.000Z"
}

Error Responses:

Critical Gotchas

These are hard-won lessons from actual deployment. Read carefully.

1. Base Image Must Be cloudflare/sandbox

# CORRECT
FROM docker.io/cloudflare/sandbox:0.7.0

# WRONG - causes Error 1101
FROM node:20-slim

2. Use getSandbox() API

// CORRECT
import { getSandbox } from "@cloudflare/sandbox";
const sandbox = getSandbox(env.Sandbox, "unique-id");

// WRONG - older API
const sandbox = await Sandbox.create(env.SANDBOX, {...});

3. Export the Sandbox Class

// REQUIRED in index.ts
export { Sandbox } from "@cloudflare/sandbox";

4. Use --permission-mode, NOT --dangerously-skip-permissions

// CORRECT - works in sandbox (runs as root)
const cmd = `claude -p "${task}" --permission-mode acceptEdits`;

// WRONG - fails because sandbox runs as root
const cmd = `claude --dangerously-skip-permissions -p "${task}"`;

5. Binding Name Must Match

// wrangler.jsonc
"durable_objects": {
  "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
}

// index.ts - must match "name" above
interface Env {
  Sandbox: DurableObjectNamespace;
}

6. containers:write Permission Required

npx wrangler login
# Ensure containers:write is granted

Required Configuration

Dockerfile

FROM docker.io/cloudflare/sandbox:0.7.0
RUN npm install -g @anthropic-ai/claude-code
ENV COMMAND_TIMEOUT_MS=300000
EXPOSE 3000

wrangler.jsonc

{
  "containers": [{
    "class_name": "Sandbox",
    "image": "./Dockerfile",
    "instance_type": "standard-1",
    "max_instances": 5
  }],
  "durable_objects": {
    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
  },
  "migrations": [{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" }]
}

Common Errors

Security Considerations

Token Management

SERVER_AUTH_TOKEN:

• Generate with ./Tools/generate-token.sh (256-bit entropy)
• Store securely - this grants full API access
• Rotate periodically (recommended: quarterly)
• Never commit to version control

CLAUDE_CODE_OAUTH_TOKEN:

• Generated via claude setup-token
• Tied to your Claude MAX subscription
• Expires and needs periodic refresh
• Set as Wrangler secret, never in code

Token Rotation

# Rotate SERVER_AUTH_TOKEN
./Tools/generate-token.sh
npx wrangler secret put SERVER_AUTH_TOKEN
# Update all clients with new token

# Refresh CLAUDE_CODE_OAUTH_TOKEN
claude setup-token
npx wrangler secret put CLAUDE_CODE_OAUTH_TOKEN
npm run deploy

Network Security

• All traffic is HTTPS (TLS 1.3)
• Cloudflare provides DDoS protection
• Worker validates auth before any sandbox access
• Containers are isolated per-task

Data Handling

Container Isolation

Each task runs in an isolated container:

• Fresh environment per execution
• No persistent state between tasks
• Resource limits enforced
• No network access to other containers

Best Practices

1. Least Privilege: Only grant necessary permissions
2. Token Rotation: Rotate tokens quarterly
3. Monitoring: Watch for unusual auth failures
4. Audit Logs: Review Cloudflare logs regularly
5. R2 Cleanup: Delete old task results periodically

Resources

• Reference Implementation: https://github.com/WellDunDun/claude-code-sandbox
• Cloudflare Sandbox Docs: https://developers.cloudflare.com/sandbox/
• Sandbox SDK GitHub: https://github.com/cloudflare/sandbox-sdk
• Claude Code Tutorial: https://developers.cloudflare.com/sandbox/tutorials/claude-code/

Costs

Typical usage: $15-40/month (excluding Claude MAX subscription).