claude-code-templates 1.24.1 → 1.24.2

package/components/sandbox/cloudflare/claude-code-sandbox.md

@@ -0,0 +1,314 @@
+# Cloudflare Claude Code Sandbox
+
+Execute Claude Code in an isolated Cloudflare Workers sandbox environment with AI-powered code execution.
+
+## Description
+
+This component sets up Cloudflare Sandbox SDK integration to run Claude Code in a secure, isolated cloud environment. Built on Cloudflare's container-based sandboxes with Durable Objects for persistent execution.
+
+## Features
+
+- **Isolated Execution**: Run Claude Code in secure Cloudflare Workers sandboxes
+- **AI Code Executor**: Turn natural language into executable Python/Node.js code
+- **Real-time Streaming**: Stream execution output as it happens
+- **Persistent Storage**: Use Durable Objects for stateful sandbox sessions
+- **Global Distribution**: Leverage Cloudflare's edge network for low latency
+- **Component Installation**: Automatically install agents and commands in sandbox
+
+## Requirements
+
+- Cloudflare Account (Workers Paid plan for Durable Objects)
+- Anthropic API Key
+- Node.js 16.17.0+
+- Docker (for local development)
+- Wrangler CLI
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│  User Request (Natural Language)                    │
+└──────────────────┬──────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────────────────┐
+│  Cloudflare Worker (API Endpoint)                   │
+│  • POST /execute                                    │
+│  • Receives question/prompt                         │
+└──────────────────┬──────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────────────────┐
+│  Claude AI (via Anthropic SDK)                      │
+│  • Generates Python/TypeScript code                 │
+│  • Returns executable implementation                │
+└──────────────────┬──────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────────────────┐
+│  Cloudflare Sandbox (Durable Object)                │
+│  • Isolated container execution                     │
+│  • Python/Node.js runtime                          │
+│  • File system access                              │
+│  • Real-time streaming output                      │
+└──────────────────┬──────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────────────────┐
+│  Results                                            │
+│  • Generated code                                   │
+│  • Execution output                                │
+│  • Error messages (if any)                         │
+└─────────────────────────────────────────────────────┘
+```
+
+## Usage
+
+```bash
+# Execute a prompt in Cloudflare sandbox
+npx claude-code-templates@latest --sandbox cloudflare --prompt "Calculate the 10th Fibonacci number"
+
+# Pass API keys directly
+npx claude-code-templates@latest --sandbox cloudflare \
+  --anthropic-api-key your_anthropic_key \
+  --prompt "Create a web scraper"
+
+# Install components and execute
+npx claude-code-templates@latest --sandbox cloudflare \
+  --agent frontend-developer \
+  --command setup-react \
+  --anthropic-api-key your_anthropic_key \
+  --prompt "Create a modern todo app"
+
+# Deploy your own Cloudflare Worker sandbox
+cd .claude/sandbox/cloudflare
+npm install
+npx wrangler secret put ANTHROPIC_API_KEY
+npx wrangler deploy
+```
+
+## Environment Setup
+
+The component creates:
+- `.claude/sandbox/cloudflare/src/index.ts` - Worker with sandbox logic
+- `.claude/sandbox/cloudflare/wrangler.toml` - Cloudflare configuration
+- `.claude/sandbox/cloudflare/package.json` - Node.js dependencies
+- `.claude/sandbox/cloudflare/launcher.ts` - TypeScript launcher script
+- `.claude/sandbox/cloudflare/monitor.ts` - Real-time monitoring tool
+
+## API Key Configuration
+
+### Option 1: CLI Parameters (Recommended)
+```bash
+npx claude-code-templates@latest --sandbox cloudflare \
+  --anthropic-api-key your_anthropic_api_key \
+  --prompt "Your prompt here"
+```
+
+### Option 2: Wrangler Secrets
+```bash
+cd .claude/sandbox/cloudflare
+npx wrangler secret put ANTHROPIC_API_KEY
+# Paste your API key when prompted
+```
+
+### Option 3: Environment Variables
+```bash
+export ANTHROPIC_API_KEY=your_anthropic_api_key_here
+
+# Or create .dev.vars file:
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+```
+
+**Note**: Wrangler secrets are required for production deployment. CLI parameters work for local execution only.
+
+## How it Works
+
+1. User sends natural language request (e.g., "What's the factorial of 5?")
+2. Cloudflare Worker receives request via POST /execute
+3. Claude generates executable Python/TypeScript code via Anthropic API
+4. Code is written to sandbox file system
+5. Sandbox executes code in isolated container
+6. Results stream back in real-time
+7. Worker returns both code and execution output
+
+## Deployment
+
+### Local Development
+```bash
+cd .claude/sandbox/cloudflare
+npm install
+npm run dev
+
+# Test locally
+curl -X POST http://localhost:8787/execute \
+  -H "Content-Type: application/json" \
+  -d '{"question": "What is 2^10?"}'
+```
+
+### Production Deployment
+```bash
+# Set API key secret
+npx wrangler secret put ANTHROPIC_API_KEY
+
+# Deploy to Cloudflare Workers
+npx wrangler deploy
+
+# Wait 2-3 minutes for container provisioning
+npx wrangler containers list
+
+# Test deployment
+curl -X POST https://your-worker.your-subdomain.workers.dev/execute \
+  -H "Content-Type: application/json" \
+  -d '{"question": "Calculate factorial of 5"}'
+```
+
+## Security Benefits
+
+- **Container Isolation**: Each execution runs in isolated Cloudflare container
+- **No Local Access**: Sandboxes have no access to your local system
+- **Resource Limits**: Automatic CPU time and memory constraints
+- **Temporary Execution**: Containers destroyed after execution
+- **Edge Security**: Cloudflare's security infrastructure built-in
+
+## Advanced Features
+
+### Code Interpreter API
+```typescript
+// Use built-in code interpreter instead of exec
+import { getCodeInterpreter } from '@cloudflare/sandbox';
+
+const interpreter = getCodeInterpreter(env.Sandbox, 'user-id');
+const result = await interpreter.notebook.execCell('print(2**10)');
+```
+
+### Streaming Output
+```typescript
+// Stream execution results in real-time
+return new Response(
+  new ReadableStream({
+    async start(controller) {
+      const result = await sandbox.exec('python script.py', {
+        onStdout: (data) => controller.enqueue(data),
+        onStderr: (data) => controller.enqueue(data)
+      });
+      controller.close();
+    }
+  })
+);
+```
+
+### Persistent Sessions
+```typescript
+// Maintain sandbox state across requests
+const sandbox = getSandbox(env.Sandbox, userId);
+await sandbox.writeFile('/data/state.json', JSON.stringify(state));
+// Later...
+const state = await sandbox.readFile('/data/state.json');
+```
+
+## Examples
+
+```bash
+# Mathematical computation
+npx claude-code-templates@latest --sandbox cloudflare \
+  --prompt "Calculate the 100th Fibonacci number"
+
+# Data analysis
+npx claude-code-templates@latest --sandbox cloudflare \
+  --prompt "What is the mean of [10, 20, 30, 40, 50]?"
+
+# String manipulation
+npx claude-code-templates@latest --sandbox cloudflare \
+  --prompt "Reverse the string 'Hello World'"
+
+# Web development
+npx claude-code-templates@latest --sandbox cloudflare \
+  --agent frontend-developer \
+  --prompt "Create a responsive navigation bar"
+```
+
+## Comparison with E2B
+
+| Feature | Cloudflare Sandbox | E2B Sandbox |
+|---------|-------------------|-------------|
+| **Provider** | Cloudflare Workers | E2B.dev |
+| **Infrastructure** | Cloudflare Edge Network | Cloud VMs |
+| **Pricing** | $5/month (Workers Paid) | Usage-based |
+| **Cold Start** | ~100ms | ~2-3 seconds |
+| **Max Duration** | 30 seconds (Workers) | Up to hours |
+| **Languages** | Python, Node.js | Full Linux environment |
+| **Global** | Yes (edge network) | Single region |
+| **Best For** | Fast, lightweight tasks | Long-running operations |
+
+## Troubleshooting
+
+### Container Not Ready
+```bash
+# After first deployment, wait 2-3 minutes
+npx wrangler containers list
+
+# Check container status
+npx wrangler tail
+```
+
+### API Key Issues
+```bash
+# Verify secret is set
+npx wrangler secret list
+
+# Update secret
+npx wrangler secret put ANTHROPIC_API_KEY
+```
+
+### Local Development Issues
+```bash
+# Ensure Docker is running
+docker ps
+
+# Clear wrangler cache
+rm -rf .wrangler
+
+# Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+```
+
+## Performance Tips
+
+1. **Use Code Interpreter API** for better Python performance
+2. **Implement caching** for frequently used code patterns
+3. **Stream output** for long-running operations
+4. **Use Durable Objects** for session persistence
+5. **Deploy to multiple regions** (automatic with Workers)
+
+## Template Information
+
+- **Provider**: Cloudflare Workers + Sandbox SDK
+- **Runtime**: V8 isolates with container sandboxes
+- **Languages**: Python 3.x, Node.js
+- **Timeout**: 30 seconds (Workers), configurable for Durable Objects
+- **Memory**: 128MB default
+- **Storage**: Ephemeral (use Durable Objects for persistence)
+
+## Resources
+
+- [Cloudflare Sandbox SDK Docs](https://developers.cloudflare.com/sandbox/)
+- [Workers Documentation](https://developers.cloudflare.com/workers/)
+- [Durable Objects Guide](https://developers.cloudflare.com/durable-objects/)
+- [Wrangler CLI Reference](https://developers.cloudflare.com/workers/wrangler/)
+- [Anthropic API Documentation](https://docs.anthropic.com/)
+
+## Next Steps
+
+After installation:
+1. Set up Cloudflare account and get API credentials
+2. Install Wrangler CLI: `npm install -g wrangler`
+3. Configure secrets: `npx wrangler secret put ANTHROPIC_API_KEY`
+4. Deploy your worker: `npx wrangler deploy`
+5. Test with example requests
+6. Customize sandbox configuration for your use case
+
+## License
+
+Uses Cloudflare Sandbox SDK (open source) and requires Cloudflare Workers Paid plan ($5/month) for Durable Objects support.