davila7--claude-code-templates/cli-tool/components/sandbox/cloudflare/SANDBOX_DEBUGGING.md

Cloudflare Sandbox Debugging Guide

🔍 Available Monitoring Tools

1. Launcher with Enhanced Logging

File: launcher.ts

• Detailed logging of each execution step
• Worker availability checks
• Code generation monitoring
• Fallback to direct execution if worker unavailable
• Colored terminal output for better readability

2. Real-time Monitor

File: monitor.ts

• Real-time performance metrics tracking
• Worker health monitoring
• Code generation time analysis
• Sandbox execution monitoring
• Memory usage tracking
• Comprehensive error reporting

3. Wrangler CLI Tools

Built-in Cloudflare debugging tools:

• npx wrangler tail - Real-time log streaming
• npx wrangler containers list - Container status
• npx wrangler deployments list - Deployment history
• npx wrangler dev - Local development server

🚨 Common Troubleshooting

Problem: "Container not ready"

Symptoms:

Error: Container not ready. Please wait 2-3 minutes after deployment.

Solutions:

1. Wait for provisioning:

   # Check container status
   npx wrangler containers list
   
   # Expected output after provisioning:
   # ✓ Container ready for sandbox execution
   

2. Verify deployment:

   npx wrangler deployments list
   # Check deployment status and timestamp
   

3. Check worker logs:

   npx wrangler tail
   # Look for initialization errors
   

Problem: "Worker not responding"

Symptoms:

❌ Worker health check failed: fetch failed

Debugging Steps:

1. Verify worker is deployed:

   npx wrangler deploy
   # Should return worker URL
   

2. Test worker endpoint:

   curl https://your-worker.your-subdomain.workers.dev
   # Should return usage instructions
   

3. Check local development:

   # For local testing
   npm run dev
   
   # Test local endpoint
   curl http://localhost:8787
   

Problem: "Anthropic API key not set"

Symptoms:

Error: ANTHROPIC_API_KEY is required

Solutions:

1. Set as Wrangler secret (Production):

   npx wrangler secret put ANTHROPIC_API_KEY
   # Paste your key when prompted
   

2. Set in .dev.vars (Local Development):

   # Create .dev.vars file:
   echo "ANTHROPIC_API_KEY=sk-ant-your-key-here" > .dev.vars
   

3. Verify secret is set:

   npx wrangler secret list
   # Should show ANTHROPIC_API_KEY
   

Problem: "Sandbox execution timeout"

Symptoms:

Error: Sandbox execution exceeded 30 second timeout

Solutions:

1. Use Durable Objects for longer operations:

   // In wrangler.toml, ensure Durable Objects are configured
   [[durable_objects.bindings]]
   name = "Sandbox"
   class_name = "Sandbox"
   

2. Optimize code generation:

   // Request more concise code
   const prompt = `Generate SIMPLE Python code...`;
   

3. Break into smaller tasks:

   # Instead of complex operations, break into steps
   npx claude-code-templates --sandbox cloudflare \
     --prompt "Step 1: Create data structure"
   

Problem: "Docker not running" (Local Development)

Symptoms:

Error: Docker daemon is not running

Solutions:

1. Start Docker Desktop:

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

2. Verify Docker is running:

   docker ps
   # Should list running containers
   

3. Alternative: Deploy directly to Cloudflare:

   # Skip local testing, deploy directly
   npx wrangler deploy
   

📊 Using the Monitor for Debugging

Basic Monitoring Command:

# Monitor a simple operation
node monitor.ts "Calculate factorial of 5" your_api_key

# Monitor with custom worker URL
node monitor.ts "Fibonacci 10" your_api_key https://your-worker.workers.dev

Monitor Output Example:

[14:32:15] ℹ 🚀 Starting enhanced Cloudflare sandbox monitoring
============================================================
🖥️  SYSTEM INFORMATION
============================================================

Node.js Version: v20.11.0
Platform: darwin
Architecture: arm64
Memory Usage: 45MB / 128MB

============================================================

[14:32:16] ℹ 🔍 Checking Cloudflare Worker health...
[14:32:16] ✓ Worker is responding
[14:32:16] ℹ    Status: 200 OK

[14:32:17] ℹ 🤖 Starting code generation with Claude...
[14:32:19] ✓ Code generated in 2147ms
[14:32:19] ℹ    Model: claude-sonnet-4-5-20250929
[14:32:19] ℹ    Tokens used: 156 in, 89 out
[14:32:19] ℹ    Code length: 234 characters

[14:32:19] ℹ ⚙️  Executing in Cloudflare Sandbox...
[14:32:21] ✓ Sandbox execution completed in 1856ms
[14:32:21] ℹ    Exit code: 0 (success)
[14:32:21] ℹ    Output length: 3 characters

============================================================
📊 PERFORMANCE METRICS
============================================================

Total Execution Time: 4123ms
  ├─ Code Generation: 2147ms
  └─ Sandbox Execution: 1856ms
Memory Usage: 48MB

Status: Success ✓
============================================================

🎯 Debugging Specific Scenarios

1. Code Generation Issues

# Use monitor to see exact Claude API interaction
node monitor.ts "Complex prompt that might fail"

# Look for:
# - Token usage (may hit limits)
# - Generated code preview
# - Model used (should be claude-sonnet-4-5)

2. Sandbox Execution Problems

# Check worker logs while testing
npx wrangler tail &
node launcher.ts "Test prompt"

# Look for:
# - Sandbox creation errors
# - File write failures
# - Python execution errors

3. Performance Issues

# Use monitor to identify bottlenecks
node monitor.ts "Your prompt"

# Compare metrics:
# - Code Generation Time (Claude API)
# - Sandbox Execution Time (Cloudflare)
# - Total Round Trip Time

4. Network/Deployment Issues

# Check deployments
npx wrangler deployments list

# View recent logs
npx wrangler tail --format=pretty

# Test worker health
curl -v https://your-worker.workers.dev

🛠 Advanced Configuration

Enable Debug Mode:

# In wrangler.toml
[env.development]
vars = { DEBUG = "true" }

# Or in .dev.vars for local development
DEBUG=true
ANTHROPIC_API_KEY=your_key

Custom Timeouts:

// In src/index.ts
const result = await sandbox.exec('python /tmp/code.py', {
  timeout: 60000, // 60 seconds
});

Verbose Logging:

# Set log level
export WRANGLER_LOG=debug

# Run with verbose output
npx wrangler deploy --verbose

📋 Debugging Checklist

Before Reporting an Issue:

• Cloudflare Workers account active (Paid plan if using Durable Objects)
• Anthropic API key valid and has credits
• Worker deployed successfully (npx wrangler deploy)
• Waited 2-3 minutes after first deployment
• Containers provisioned (npx wrangler containers list)
• Secrets configured (npx wrangler secret list)
• Docker running (for local development)
• Used monitor tool for detailed metrics
• Checked worker logs (npx wrangler tail)
• Tested with simple prompt first

Information to Include in Bug Reports:

• Full monitor output showing timestamps and metrics
• Worker URL or local development environment
• Exact prompt that caused the issue
• Components installed (if applicable)
• Worker logs from npx wrangler tail
• Container status from npx wrangler containers list
• Error messages with full stack traces
• Node.js and Wrangler versions

🚀 Performance Optimization Tips

1. Minimize Code Generation Time

// Be specific to reduce Claude's thinking time
const prompt = `Generate a single Python function to calculate factorial.
Use recursion. Include only the function, no tests.`;

2. Use Code Interpreter API

// Faster than exec for Python
import { getCodeInterpreter } from '@cloudflare/sandbox';
const interpreter = getCodeInterpreter(env.Sandbox, userId);
const result = await interpreter.notebook.execCell(pythonCode);

3. Implement Caching

// Cache generated code for common prompts
const cacheKey = `code:${hashPrompt(prompt)}`;
let code = await env.CACHE.get(cacheKey);
if (!code) {
  code = await generateCode(prompt);
  await env.CACHE.put(cacheKey, code, { expirationTtl: 3600 });
}

4. Stream Responses

// Stream output for better perceived performance
return new Response(
  new ReadableStream({
    async start(controller) {
      const result = await sandbox.exec(command, {
        onStdout: (data) => controller.enqueue(encoder.encode(data)),
      });
      controller.close();
    },
  })
);

🔗 Useful Commands Reference

Deployment & Management

# Deploy worker
npx wrangler deploy

# Deploy to specific environment
npx wrangler deploy --env production

# Rollback deployment
npx wrangler rollback

# Delete deployment
npx wrangler delete

Secrets Management

# Add secret
npx wrangler secret put SECRET_NAME

# List secrets
npx wrangler secret list

# Delete secret
npx wrangler secret delete SECRET_NAME

Local Development

# Start dev server
npm run dev

# Start with specific port
npx wrangler dev --port 3000

# Start with remote Durable Objects
npx wrangler dev --remote

Monitoring & Logs

# Tail logs in real-time
npx wrangler tail

# Tail with pretty formatting
npx wrangler tail --format=pretty

# Tail specific deployment
npx wrangler tail --deployment-id <id>

# Filter logs
npx wrangler tail --status error

Container Management

# List containers
npx wrangler containers list

# Get container details
npx wrangler containers describe <container-id>

💡 Tips & Best Practices

1. Always test locally first: Use npm run dev before deploying
2. Monitor metrics: Use the monitor tool to track performance
3. Check logs regularly: Set up npx wrangler tail during testing
4. Use environment-specific configs: Separate dev/prod in wrangler.toml
5. Implement error handling: Catch and log all errors properly
6. Set appropriate timeouts: Balance between user experience and resource usage
7. Use Durable Objects wisely: Only for stateful operations
8. Cache aggressively: Reduce API calls with smart caching
9. Stream when possible: Better UX for long operations
10. Version your deployments: Tag releases for easy rollback

---

With these tools and techniques, you can effectively debug and optimize your Cloudflare sandbox implementation.