Cloudflare Sandbox Quick Start Guide

Cloudflare Sandbox Quick Start Guide

Get your Cloudflare Claude Code Sandbox running in under 5 minutes.

Prerequisites Checklist

• Cloudflare account (sign up at https://dash.cloudflare.com/sign-up)
• Anthropic API key (get from https://console.anthropic.com/)
• Node.js 16.17.0+ installed
• Docker installed and running (for local development)

Option 1: Deploy to Production (Fastest)

Perfect if you want to skip local testing and deploy directly.

Step 1: Install Dependencies

cd .claude/sandbox/cloudflare
npm install

Step 2: Set API Key

npx wrangler secret put ANTHROPIC_API_KEY
# Paste your Anthropic API key when prompted

Step 3: Deploy

npx wrangler deploy

Step 4: Wait for Container Provisioning

# Wait 2-3 minutes, then check:
npx wrangler containers list
# You should see: ✓ Container ready

Step 5: Test Your Deployment

# Get your worker URL from the deploy output, then:
curl -X POST https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/execute \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the 10th Fibonacci number?"}'

Expected response:

{
  "success": true,
  "question": "What is the 10th Fibonacci number?",
  "code": "def fibonacci(n):\n    ...",
  "output": "55\n",
  "error": "",
  "executionTime": 1234
}

Done! Your sandbox is live at the edge.

Option 2: Local Development First

Perfect if you want to test locally before deploying.

Step 1: Install Dependencies

cd .claude/sandbox/cloudflare
npm install

Step 2: Create Local Environment File

cp .dev.vars.example .dev.vars
# Edit .dev.vars and add your Anthropic API key

Step 3: Start Docker

# macOS: Open Docker Desktop
# Linux: sudo systemctl start docker
# Windows: Start Docker Desktop

# Verify Docker is running:
docker ps

Step 4: Start Development Server

npm run dev

Wait for:

⛅️ wrangler 3.78.12
-------------------
⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787

Step 5: Test Locally

# In a new terminal:
curl -X POST http://localhost:8787/execute \
  -H "Content-Type: application/json" \
  -d '{"question": "Calculate factorial of 5"}'

Step 6: Deploy When Ready

# Stop the dev server (Ctrl+C)
npx wrangler secret put ANTHROPIC_API_KEY
npx wrangler deploy

Done! You've tested locally and deployed.

Option 3: Using the CLI Tools

Perfect if you prefer command-line interaction.

Step 1: Setup (same as above)

cd .claude/sandbox/cloudflare
npm install
npx wrangler secret put ANTHROPIC_API_KEY
npx wrangler deploy

Step 2: Use the Launcher

# Execute a prompt
node launcher.ts "What is 2 to the power of 10?" \
  "" \
  your_anthropic_key \
  https://your-worker.workers.dev

Step 3: Use the Monitor (for debugging)

# Get detailed execution metrics
node monitor.ts "Calculate factorial of 5" \
  your_anthropic_key \
  https://your-worker.workers.dev

Done! You're using the CLI tools.

Common Issues & Quick Fixes

"Container not ready"

Solution: Wait 2-3 minutes after first deployment

npx wrangler containers list

"Docker daemon is not running"

Solution: Start Docker Desktop or Docker service

docker ps  # Should list containers

"ANTHROPIC_API_KEY not configured"

Solution: Set the secret

# Production:
npx wrangler secret put ANTHROPIC_API_KEY

# Local (.dev.vars):
echo "ANTHROPIC_API_KEY=sk-ant-your-key" > .dev.vars

"Worker not found"

Solution: Deploy the worker

npx wrangler deploy

"Execution timeout"

Solution: Increase timeout in request

{
  "question": "Your question",
  "timeout": 60000
}

Next Steps

1. Customize Your Worker

Edit src/index.ts to add custom logic:

• Add authentication
• Implement rate limiting
• Add custom error handling
• Create specialized endpoints

2. Add Monitoring

# Watch logs in real-time
npx wrangler tail

# Use the monitor tool
node monitor.ts "your prompt" your_api_key

3. Test Different Languages

# Python (default)
curl -X POST https://your-worker.workers.dev/execute \
  -d '{"question": "Fibonacci", "language": "python"}'

# JavaScript
curl -X POST https://your-worker.workers.dev/execute \
  -d '{"question": "Fibonacci", "language": "javascript"}'

4. Integrate with Your App

// Frontend integration
const response = await fetch('https://your-worker.workers.dev/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ question: 'Calculate factorial of 5' })
});

const result = await response.json();
console.log(result.output);

5. Enable Advanced Features

See the main README.md for:

• Streaming output
• Code Interpreter API
• Caching strategies
• Performance optimization

Resources

• Documentation: README.md
• Debugging: SANDBOX_DEBUGGING.md
• Component Info: claude-code-sandbox.md
• Cloudflare Docs: https://developers.cloudflare.com/sandbox/
• Anthropic Docs: https://docs.anthropic.com/

Getting Help

1. Check logs: npx wrangler tail
2. Use monitor: node monitor.ts "test" your_key
3. Read debugging guide: SANDBOX_DEBUGGING.md
4. Check container status: npx wrangler containers list
5. Test health: curl https://your-worker.workers.dev/health

You're all set! Start executing code with Claude AI on Cloudflare's edge network.