{"content": "# Docker Claude Code Sandbox\n\nExecute Claude Code in isolated Docker containers with AI-powered code generation using the Claude Agent SDK.\n\n## Quick Start\n\n### 1. Install Docker\n\nEnsure Docker is installed and running on your system:\n\n```bash\n# Check Docker installation\ndocker --version\n\n# Verify Docker daemon is running\ndocker ps\n```\n\nIf Docker is not installed, visit: https://docs.docker.com/get-docker/\n\n### 2. Configure API Key\n\nSet your Anthropic API key:\n\n```bash\n# Set as environment variable\nexport ANTHROPIC_API_KEY=sk-ant-your-api-key-here\n\n# Or pass directly when using the CLI\nnpx claude-code-templates@latest --sandbox docker \\\n --agent development/frontend-developer \\\n --prompt \"Create a React component\" \\\n --anthropic-api-key sk-ant-your-key\n```\n\n### 3. Run Your First Sandbox\n\n```bash\n# Basic execution\nnpx claude-code-templates@latest --sandbox docker \\\n --prompt \"Write a function to calculate factorial\"\n\n# With specific agent\nnpx claude-code-templates@latest --sandbox docker \\\n --agent development/python-developer \\\n --prompt \"Create a data validation script\"\n\n# With multiple components\nnpx claude-code-templates@latest --sandbox docker \\\n --agent development/fullstack-developer \\\n --command development/setup-testing \\\n --prompt \"Set up a complete testing environment\"\n```\n\n## Architecture\n\nThis sandbox combines two powerful technologies:\n\n1. **Claude Agent SDK** - Provides programmatic access to Claude Code\n2. **Docker** - Provides isolated container execution\n\n```\nUser Prompt → Docker Launcher → Container Build → Execute Script → Claude Agent SDK → Output Files\n```\n\n### Components\n\n```\ndocker/\n├── docker-launcher.js # Node.js launcher that orchestrates Docker\n├── Dockerfile # Container definition with Claude Agent SDK\n├── execute.js # Script that runs inside container\n├── package.json # Dependencies (Claude Agent SDK)\n└── README.md # This file\n```\n\n## How It Works\n\n### 1. Launcher Phase (docker-launcher.js)\n- Checks Docker installation and daemon status\n- Builds container image if it doesn't exist\n- Prepares environment variables and volume mounts\n- Launches container with user prompt\n\n### 2. Container Phase (execute.js)\n- Installs requested components (agents, commands, MCPs, etc.)\n- Executes Claude Agent SDK with the user's prompt\n- Auto-allows all tool uses (no permission prompts)\n- Captures output and generated files\n- Copies results to mounted output directory\n\n### 3. Output Phase\n- Generated files are saved to `output/` directory\n- Files preserve directory structure\n- Accessible on host machine for inspection\n\n## Usage Examples\n\n### Simple Code Generation\n\n```bash\nnpx claude-code-templates@latest --sandbox docker \\\n --prompt \"Create a REST API server with Express.js\"\n```\n\n### With Specific Agent\n\n```bash\nnpx claude-code-templates@latest --sandbox docker \\\n --agent security/security-auditor \\\n --prompt \"Audit this codebase for security vulnerabilities\"\n```\n\n### Multiple Components\n\n```bash\nnpx claude-code-templates@latest --sandbox docker \\\n --agent development/frontend-developer \\\n --command testing/setup-testing \\\n --setting performance/performance-optimization \\\n --prompt \"Create a React app with testing setup\"\n```\n\n### Development Workflow\n\n```bash\n# 1. Generate initial code\nnpx claude-code-templates@latest --sandbox docker \\\n --agent development/fullstack-developer \\\n --prompt \"Create a blog API with authentication\"\n\n# 2. Check output\nls -la output/\n\n# 3. Iterate on generated code\nnpx claude-code-templates@latest --sandbox docker \\\n --prompt \"Add pagination to the blog API\"\n```\n\n## Configuration\n\n### Environment Variables\n\n**Required:**\n- `ANTHROPIC_API_KEY` - Your Anthropic API key\n\n**Optional:**\n- `DOCKER_BUILDKIT=1` - Enable BuildKit for faster builds\n\n### Docker Image Details\n\nThe Docker image (`claude-sandbox`) includes:\n\n- **Base**: Node.js 22 Alpine Linux (minimal, secure)\n- **Runtime**: Git, Bash, Python3, Pip, Curl\n- **Claude SDK**: `@anthropic-ai/claude-agent-sdk` installed globally\n- **Security**: Runs as non-root user (UID 10001)\n- **Working Directory**: `/app`\n- **Output Directory**: `/output` (mounted as volume)\n\n### Build Configuration\n\nEdit `Dockerfile` to customize:\n\n```dockerfile\n# Add additional system dependencies\nRUN apk --no-cache add postgresql-client redis\n\n# Install additional global npm packages\nRUN npm install -g typescript tsx\n\n# Set custom environment variables\nENV CUSTOM_VAR=value\n```\n\n## Command Reference\n\n### Build Image Manually\n\n```bash\ncd .claude/sandbox/docker\ndocker build -t claude-sandbox .\n```\n\n### Run Container Directly\n\n```bash\ndocker run --rm \\\n -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \\\n -v $(pwd)/output:/output \\\n claude-sandbox \\\n node /app/execute.js \"Your prompt here\" \"\"\n```\n\n### Clean Up\n\n```bash\n# Remove built image\ndocker rmi claude-sandbox\n\n# Remove all stopped containers\ndocker container prune\n\n# Remove dangling images\ndocker image prune\n```\n\n## Troubleshooting\n\n### Docker Not Found\n\n**Error:** `Docker is not installed`\n\n**Solution:**\n```bash\n# Install Docker from official site\n# macOS: https://docs.docker.com/desktop/install/mac-install/\n# Linux: https://docs.docker.com/engine/install/\n# Windows: https://docs.docker.com/desktop/install/windows-install/\n```\n\n### Docker Daemon Not Running\n\n**Error:** `Docker daemon is not running`\n\n**Solution:**\n```bash\n# macOS/Windows: Start Docker Desktop application\n# Linux: sudo systemctl start docker\n```\n\n### API Key Not Set\n\n**Error:** `ANTHROPIC_API_KEY environment variable is required`\n\n**Solution:**\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n```\n\n### Build Failures\n\n**Error:** Failed to build Docker image\n\n**Solution:**\n```bash\n# Check Docker logs\ndocker logs <container-id>\n\n# Rebuild from scratch\ndocker build --no-cache -t claude-sandbox .\n\n# Check disk space\ndocker system df\n```\n\n### Permission Issues\n\n**Error:** Permission denied when accessing output files\n\n**Solution:**\n```bash\n# Check output directory permissions\nls -la output/\n\n# Fix permissions (if needed)\nsudo chown -R $USER:$USER output/\n```\n\n### Container Execution Failures\n\n**Error:** Container failed with code 1\n\n**Solution:**\n```bash\n# Run container interactively for debugging\ndocker run -it --rm \\\n -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \\\n claude-sandbox \\\n /bin/bash\n\n# Check container logs\ndocker logs <container-id>\n```\n\n## Performance Tips\n\n1. **Image Caching**: First build takes longer, subsequent builds are fast\n2. **Volume Mounts**: Use volumes instead of COPY for faster iteration\n3. **Layer Optimization**: Group RUN commands to reduce image layers\n4. **BuildKit**: Enable for parallel builds (`DOCKER_BUILDKIT=1`)\n5. **Prune Regularly**: Clean up unused images and containers\n\n## Security\n\n- **Isolation**: Containers are isolated from host system\n- **Non-root User**: Execution runs as `sandboxuser` (UID 10001)\n- **No Network**: Container has no internet access (except during build)\n- **Read-only**: Host filesystem is mounted read-only\n- **Resource Limits**: Docker enforces CPU and memory limits\n- **Secret Management**: API keys are passed as environment variables (not stored in image)\n\n## Cost Estimation\n\n**Docker:**\n- Free and open-source\n- No cloud costs (runs locally)\n- Resource usage: ~500MB disk space, ~512MB RAM during execution\n\n**Anthropic API:**\n- Claude Sonnet 4.5: ~$3 per million input tokens\n- Average request: ~200 tokens = $0.0006 per request\n\n**Example costs for 100 executions:**\n- Docker: $0 (local execution)\n- Anthropic: ~$0.06 (avg 200 tokens/request)\n- **Total: ~$0.06**\n\n## Comparison with Other Providers\n\n| Feature | Docker | E2B | Cloudflare |\n|---------|--------|-----|------------|\n| Execution Location | 🏠 Local | ☁️ Cloud | 🌍 Edge |\n| Setup Complexity | Medium | Easy | Easy |\n| Internet Required | Setup only | Yes | Yes |\n| Cost | Free | Paid | Paid |\n| Privacy | Full control | Third-party | Third-party |\n| Offline Support | Yes | No | No |\n| Best For | Local dev, privacy, offline | Full stack projects | Serverless, global APIs |\n\n## Development\n\n### Project Structure\n\n```\ndocker/\n├── docker-launcher.js # Orchestrates container lifecycle\n│ ├── checkDockerInstalled()\n│ ├── checkDockerRunning()\n│ ├── buildDockerImage()\n│ └── runDockerContainer()\n├── Dockerfile # Container definition\n│ ├── Base image (Node 22 Alpine)\n│ ├── System dependencies\n│ ├── Claude Agent SDK\n│ └── Security (non-root user)\n├── execute.js # Execution script (runs in container)\n│ ├── installComponents()\n│ ├── executeQuery()\n│ └── copyGeneratedFiles()\n├── package.json # NPM dependencies\n└── README.md # Documentation\n```\n\n### Scripts\n\n```bash\n# Build image\nnpm run build\n\n# Clean image\nnpm run clean\n```\n\n### Extending the Image\n\nAdd custom tools to the Dockerfile:\n\n```dockerfile\n# Install Python packages\nRUN pip install --no-cache-dir pandas numpy matplotlib\n\n# Install Node.js packages globally\nRUN npm install -g typescript eslint prettier\n\n# Add custom scripts\nCOPY scripts/ /app/scripts/\n```\n\n## Advanced Usage\n\n### Custom Dockerfile\n\nCreate a custom Dockerfile for specialized environments:\n\n```dockerfile\nFROM node:22-alpine\n\n# Install database clients\nRUN apk add --no-cache postgresql-client mysql-client\n\n# Install development tools\nRUN apk add --no-cache vim nano tmux\n\n# Install Claude Agent SDK\nRUN npm install -g @anthropic-ai/claude-agent-sdk\n\n# ... rest of configuration\n```\n\n### Multi-stage Builds\n\nOptimize image size with multi-stage builds:\n\n```dockerfile\n# Build stage\nFROM node:22-alpine AS builder\nWORKDIR /build\nCOPY package*.json ./\nRUN npm ci --only=production\n\n# Runtime stage\nFROM node:22-alpine\nCOPY --from=builder /build/node_modules ./node_modules\n# ... rest of configuration\n```\n\n### Persistent Storage\n\nMount additional volumes for persistent data:\n\n```bash\ndocker run --rm \\\n -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \\\n -v $(pwd)/output:/output \\\n -v $(pwd)/cache:/cache \\\n claude-sandbox\n```\n\n## Resources\n\n- [Docker Documentation](https://docs.docker.com/)\n- [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk)\n- [Anthropic API Documentation](https://docs.anthropic.com/)\n- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)\n- [Container Security](https://docs.docker.com/engine/security/)\n\n## License\n\nMIT License - See LICENSE file for details\n\n## Support\n\nFor issues and questions:\n1. Check Docker installation: `docker --version && docker ps`\n2. Verify API key: `echo $ANTHROPIC_API_KEY`\n3. Check container logs: `docker logs <container-id>`\n4. Review output directory: `ls -la output/`\n5. Open an issue on GitHub\n\n---\n\nBuilt with ❤️ using Docker, Node.js, and Claude Agent SDK\n"}
wehub-resource-sync