claude-code-templates 1.26.4 → 1.27.0

package/components/sandbox/docker/Dockerfile

@@ -0,0 +1,38 @@
+# syntax=docker/dockerfile:1
+FROM node:22-alpine
+
+# Install runtime dependencies
+RUN apk --no-cache add \
+    git \
+    bash \
+    python3 \
+    py3-pip \
+    curl \
+    && npm install -g @anthropic-ai/claude-agent-sdk
+
+# Create non-root user for security
+RUN adduser -u 10001 -D -s /bin/bash sandboxuser
+
+# Set working directory
+WORKDIR /app
+
+# Create output directory
+RUN mkdir -p /output && chown sandboxuser:sandboxuser /output
+
+# Copy execution script
+COPY execute.js /app/execute.js
+COPY package.json /app/package.json
+
+# Install dependencies
+RUN npm install --production && \
+    chown -R sandboxuser:sandboxuser /app
+
+# Switch to non-root user
+USER sandboxuser
+
+# Set environment
+ENV HOME=/home/sandboxuser
+ENV NODE_ENV=production
+
+# Default command (overridden by launcher)
+CMD ["node", "/app/execute.js"]

package/components/sandbox/docker/README.md

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

package/components/sandbox/docker/docker-launcher.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+/**
+ * Docker Sandbox Launcher
+ * Orchestrates Docker container execution for Claude Code
+ */
+
+import { spawn, execSync } from 'child_process';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const prompt = args[0] || 'Hello, Claude!';
+const componentsToInstall = args[1] || '';
+const anthropicApiKey = process.env.ANTHROPIC_API_KEY;
+
+// Validate API key
+if (!anthropicApiKey) {
+  console.error('❌ Error: ANTHROPIC_API_KEY environment variable is required');
+  process.exit(1);
+}
+
+console.log('🐳 Docker Sandbox Launcher');
+console.log('═══════════════════════════════════════\n');
+
+/**
+ * Check if Docker is installed
+ */
+function checkDockerInstalled() {
+  try {
+    execSync('docker --version', { stdio: 'pipe' });
+    return true;
+  } catch (error) {
+    console.error('❌ Error: Docker is not installed');
+    console.error('   Please install Docker: https://docs.docker.com/get-docker/\n');
+    return false;
+  }
+}
+
+/**
+ * Check if Docker daemon is running
+ */
+function checkDockerRunning() {
+  try {
+    execSync('docker ps', { stdio: 'pipe' });
+    return true;
+  } catch (error) {
+    console.error('❌ Error: Docker daemon is not running');
+    console.error('   Please start Docker and try again\n');
+    return false;
+  }
+}
+
+/**
+ * Build Docker image if it doesn't exist
+ */
+async function buildDockerImage() {
+  console.log('🔨 Checking Docker image...');
+
+  // Check if image exists
+  try {
+    execSync('docker image inspect claude-sandbox', { stdio: 'pipe' });
+    console.log('   ✅ Image already exists\n');
+    return true;
+  } catch (error) {
+    // Image doesn't exist, build it
+    console.log('   📦 Building Docker image (this may take a few minutes)...\n');
+
+    return new Promise((resolve) => {
+      const build = spawn('docker', [
+        'build',
+        '-t', 'claude-sandbox',
+        '.'
+      ], {
+        cwd: __dirname,
+        stdio: 'inherit'
+      });
+
+      build.on('close', (code) => {
+        if (code === 0) {
+          console.log('\n✅ Docker image built successfully\n');
+          resolve(true);
+        } else {
+          console.error('\n❌ Failed to build Docker image');
+          resolve(false);
+        }
+      });
+
+      build.on('error', (error) => {
+        console.error('❌ Build error:', error.message);
+        resolve(false);
+      });
+    });
+  }
+}
+
+/**
+ * Run Docker container
+ */
+async function runDockerContainer() {
+  console.log('🚀 Starting Docker container...\n');
+
+  // Create output directory
+  const outputDir = path.join(process.cwd(), 'output');
+  await fs.mkdir(outputDir, { recursive: true });
+
+  return new Promise((resolve) => {
+    const dockerArgs = [
+      'run',
+      '--rm',
+      '-e', `ANTHROPIC_API_KEY=${anthropicApiKey}`,
+      '-v', `${outputDir}:/output`,
+      'claude-sandbox',
+      'node', '/app/execute.js',
+      prompt,
+      componentsToInstall
+    ];
+
+    const container = spawn('docker', dockerArgs, {
+      stdio: 'inherit'
+    });
+
+    container.on('close', (code) => {
+      if (code === 0) {
+        console.log('\n✅ Docker container completed successfully');
+
+        // Show output directory
+        console.log(`\n📂 Output files saved to: ${outputDir}`);
+        resolve(true);
+      } else {
+        console.error('\n❌ Docker container failed with code:', code);
+        resolve(false);
+      }
+    });
+
+    container.on('error', (error) => {
+      console.error('❌ Container error:', error.message);
+      resolve(false);
+    });
+  });
+}
+
+/**
+ * Main execution flow
+ */
+async function main() {
+  try {
+    // Step 1: Check Docker installation
+    if (!checkDockerInstalled()) {
+      process.exit(1);
+    }
+
+    // Step 2: Check Docker daemon
+    if (!checkDockerRunning()) {
+      process.exit(1);
+    }
+
+    // Step 3: Build Docker image
+    const buildSuccess = await buildDockerImage();
+    if (!buildSuccess) {
+      process.exit(1);
+    }
+
+    // Step 4: Run container
+    const runSuccess = await runDockerContainer();
+    if (!runSuccess) {
+      process.exit(1);
+    }
+
+    console.log('\n🎉 Docker sandbox execution completed!');
+    process.exit(0);
+  } catch (error) {
+    console.error('❌ Fatal error:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run main function
+main();

package/components/sandbox/docker/execute.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+/**
+ * Docker Sandbox Executor
+ * Runs inside Docker container using Claude Agent SDK
+ */
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import fs from 'fs/promises';
+import path from 'path';
+import { spawn } from 'child_process';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const prompt = args[0] || 'Hello, Claude!';
+const componentsToInstall = args[1] || '';
+const anthropicApiKey = process.env.ANTHROPIC_API_KEY;
+
+// Validate API key
+if (!anthropicApiKey) {
+  console.error('❌ Error: ANTHROPIC_API_KEY environment variable is required');
+  process.exit(1);
+}
+
+console.log('🐳 Docker Sandbox Executor');
+console.log('═══════════════════════════════════════\n');
+
+/**
+ * Install Claude Code components if specified
+ */
+async function installComponents() {
+  if (!componentsToInstall || componentsToInstall.trim() === '') {
+    return true;
+  }
+
+  console.log('📦 Installing components...');
+  console.log(`   Components: ${componentsToInstall}\n`);
+
+  return new Promise((resolve) => {
+    const installCmd = `npx claude-code-templates@latest ${componentsToInstall} --yes`;
+
+    const child = spawn('sh', ['-c', installCmd], {
+      stdio: 'inherit',
+      env: process.env
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        console.log('\n✅ Components installed successfully\n');
+        resolve(true);
+      } else {
+        console.log('\n⚠️  Component installation had warnings (continuing...)\n');
+        resolve(true); // Continue even if installation has warnings
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Installation error: ${error.message}`);
+      resolve(false);
+    });
+  });
+}
+
+/**
+ * Execute Claude Code query using Agent SDK
+ */
+async function executeQuery() {
+  try {
+    console.log('🤖 Executing Claude Code...');
+    console.log(`   Prompt: "${prompt.substring(0, 80)}${prompt.length > 80 ? '...' : ''}"\n`);
+    console.log('─'.repeat(60));
+    console.log('📝 CLAUDE OUTPUT:');
+    console.log('─'.repeat(60) + '\n');
+
+    // Enhance prompt with working directory context
+    const enhancedPrompt = `${prompt}\n\nNote: Your current working directory is /app. When creating files, save them in the current directory (/app) so they can be captured in the output.`;
+
+    // query() returns an async generator - we need to iterate it
+    const generator = query({
+      prompt: enhancedPrompt,
+      options: {
+        apiKey: anthropicApiKey,
+        model: 'claude-sonnet-4-5',
+        permissionMode: 'bypassPermissions',  // Auto-allow all tool uses
+      }
+    });
+
+    let assistantResponses = [];
+    let messageCount = 0;
+
+    // Iterate through the async generator
+    for await (const message of generator) {
+      messageCount++;
+
+      if (message.type === 'assistant') {
+        // Extract text from assistant message content
+        if (message.message && message.message.content) {
+          const content = Array.isArray(message.message.content)
+            ? message.message.content
+            : [message.message.content];
+
+          content.forEach(block => {
+            if (block.type === 'text') {
+              console.log(block.text);
+              assistantResponses.push(block.text);
+            }
+          });
+        }
+      } else if (message.type === 'result') {
+        // Show final result metadata
+        console.log('\n' + '─'.repeat(60));
+        console.log(`✅ Execution completed (${message.num_turns} turn${message.num_turns > 1 ? 's' : ''})`);
+        console.log(`   Duration: ${message.duration_ms}ms`);
+        console.log(`   Cost: $${message.total_cost_usd.toFixed(5)}`);
+        console.log('─'.repeat(60) + '\n');
+      }
+    }
+
+    // Show response summary
+    const responseText = assistantResponses.join('\n');
+    if (responseText) {
+      console.log('📄 Response Summary:');
+      console.log(`   ${messageCount} message(s) received`);
+      console.log(`   ${assistantResponses.length} assistant response(s)`);
+      console.log(`   ${responseText.length} characters generated`);
+      console.log('');
+    }
+
+    return true;
+  } catch (error) {
+    console.error('\n❌ Execution error:', error.message);
+    if (error.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+    return false;
+  }
+}
+
+/**
+ * Find and copy generated files to output directory
+ */
+async function copyGeneratedFiles() {
+  try {
+    console.log('📁 Searching for generated files...\n');
+
+    // Common file extensions to look for
+    const extensions = [
+      'js', 'jsx', 'ts', 'tsx',
+      'py', 'html', 'css', 'scss',
+      'json', 'md', 'yaml', 'yml',
+      'txt', 'sh', 'bash'
+    ];
+
+    // Search for files in multiple directories
+    const { execSync } = await import('child_process');
+
+    const findPattern = extensions.map(ext => `-name "*.${ext}"`).join(' -o ');
+
+    // Search in /app and /tmp for generated files
+    const searchPaths = ['/app', '/tmp'];
+    let allFiles = [];
+
+    for (const searchPath of searchPaths) {
+      const findCmd = `find ${searchPath} -type f \\( ${findPattern} \\) ! -path "*/node_modules/*" ! -path "*/.npm/*" ! -path "/app/execute.js" ! -path "/app/package*.json" -newer /app/execute.js 2>/dev/null | head -50`;
+
+      try {
+        const output = execSync(findCmd, { encoding: 'utf8' });
+        const files = output.trim().split('\n').filter(f => f.trim());
+        allFiles = allFiles.concat(files);
+      } catch (error) {
+        // Continue to next search path
+      }
+    }
+
+    if (allFiles.length === 0) {
+      console.log('ℹ️  No generated files found\n');
+      return;
+    }
+
+    console.log(`📦 Found ${allFiles.length} file(s):\n`);
+
+    // Copy files to output directory preserving structure
+    let copiedCount = 0;
+    for (const file of allFiles) {
+      try {
+        // Determine relative path based on source directory
+        let relativePath;
+        if (file.startsWith('/app/')) {
+          relativePath = file.replace('/app/', '');
+        } else if (file.startsWith('/tmp/')) {
+          relativePath = file.replace('/tmp/', '');
+        } else {
+          relativePath = path.basename(file);
+        }
+
+        const outputPath = path.join('/output', relativePath);
+
+        // Create directory structure
+        await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
+        // Copy file
+        await fs.copyFile(file, outputPath);
+
+        console.log(`   ✅ ${relativePath}`);
+        copiedCount++;
+      } catch (error) {
+        console.log(`   ⚠️  Failed to copy: ${file}`);
+      }
+    }
+
+    if (copiedCount > 0) {
+      console.log(`\n✅ Copied ${copiedCount} file(s) to output directory\n`);
+    }
+  } catch (error) {
+    console.error('❌ Error copying files:', error.message);
+  }
+}
+
+/**
+ * Main execution flow
+ */
+async function main() {
+  try {
+    // Step 1: Install components
+    const installSuccess = await installComponents();
+    if (!installSuccess) {
+      console.error('❌ Component installation failed');
+      process.exit(1);
+    }
+
+    // Step 2: Execute Claude query
+    const executeSuccess = await executeQuery();
+    if (!executeSuccess) {
+      console.error('❌ Query execution failed');
+      process.exit(1);
+    }
+
+    // Step 3: Copy generated files
+    await copyGeneratedFiles();
+
+    console.log('🎉 Docker sandbox execution completed successfully!');
+    process.exit(0);
+  } catch (error) {
+    console.error('❌ Fatal error:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run main function
+main();

package/components/sandbox/docker/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "claude-code-docker-sandbox",
+  "version": "1.0.0",
+  "description": "Docker sandbox for Claude Code execution with Claude Agent SDK",
+  "main": "docker-launcher.js",
+  "type": "module",
+  "scripts": {
+    "build": "docker build -t claude-sandbox .",
+    "clean": "docker rmi claude-sandbox || true"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.30"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "claude",
+    "docker",
+    "sandbox",
+    "ai",
+    "agent"
+  ],
+  "author": "Claude Code Templates",
+  "license": "MIT"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-templates",
-  "version": "1.26.4",
+  "version": "1.27.0",
   "description": "CLI tool to setup Claude Code configurations with framework-specific commands, automation hooks and MCP Servers for your projects",
   "main": "src/index.js",
   "bin": {
@@ -94,6 +94,7 @@
     "src/",
     "components/sandbox/e2b/",
     "components/sandbox/cloudflare/",
+    "components/sandbox/docker/",
     "README.md"
   ],
   "devDependencies": {

package/src/index.js

@@ -2447,37 +2447,38 @@ async function launchClaudeCodeStudio(options, targetDir) {
 }
 
 async function executeSandbox(options, targetDir) {
-  const { sandbox, command, mcp, setting, hook, e2bApiKey, anthropicApiKey } = options;
+  const { sandbox, command, mcp, setting, hook, e2bApiKey, anthropicApiKey, yes } = options;
   let { agent, prompt } = options;
-  
+
   // Validate sandbox provider
-  if (sandbox !== 'e2b' && sandbox !== 'cloudflare') {
+  if (sandbox !== 'e2b' && sandbox !== 'cloudflare' && sandbox !== 'docker') {
     console.log(chalk.red('❌ Error: Invalid sandbox provider'));
-    console.log(chalk.yellow('💡 Available providers: e2b, cloudflare'));
+    console.log(chalk.yellow('💡 Available providers: e2b, cloudflare, docker'));
     console.log(chalk.gray('   Example: --sandbox e2b --prompt "Create a web app"'));
     console.log(chalk.gray('   Example: --sandbox cloudflare --prompt "Calculate factorial of 5"'));
+    console.log(chalk.gray('   Example: --sandbox docker --prompt "Write a function"'));
     return;
   }
-  
-  // Interactive agent selection if not provided
-  if (!agent) {
+
+  // Interactive agent selection if not provided and --yes not used
+  if (!agent && !yes) {
     const inquirer = require('inquirer');
-    
+
     console.log(chalk.blue('\n🤖 Agent Selection'));
     console.log(chalk.cyan('═══════════════════════════════════════'));
     console.log(chalk.gray('Select one or more agents for your task (use SPACE to select, ENTER to confirm).\n'));
-    
+
     // Fetch available agents
     console.log(chalk.gray('⏳ Fetching available agents...'));
     const agents = await getAvailableAgentsFromGitHub();
-    
+
     // Format agents for selection with full path
     const agentChoices = agents.map(a => ({
       name: `${a.path} ${chalk.gray(`- ${a.category}`)}`,
       value: a.path,  // This already includes folder/agent-name format
       short: a.path
     }));
-    
+
     // First ask if they want to select agents
     const { wantAgents } = await inquirer.prompt([{
       type: 'confirm',
@@ -2485,7 +2486,7 @@ async function executeSandbox(options, targetDir) {
       message: 'Do you want to select specific agents for this task?',
       default: true
     }]);
-    
+
     if (wantAgents) {
       const { selectedAgents } = await inquirer.prompt([{
         type: 'checkbox',
@@ -2495,7 +2496,7 @@ async function executeSandbox(options, targetDir) {
         pageSize: 15
         // Removed validation - allow empty selection
       }]);
-      
+
       if (selectedAgents && selectedAgents.length > 0) {
         // Join multiple agents with comma
         agent = selectedAgents.join(',');
@@ -2507,6 +2508,9 @@ async function executeSandbox(options, targetDir) {
     } else {
       console.log(chalk.yellow('⚠️ Continuing without specific agents'));
     }
+  } else if (!agent && yes) {
+    // --yes flag used without --agent, proceed without agents
+    console.log(chalk.yellow('⚠️ No agent specified, continuing without specific agents'));
   }
   
   // Get prompt from user if not provided
@@ -2603,6 +2607,19 @@ async function executeSandbox(options, targetDir) {
 
     // Execute Cloudflare sandbox
     await executeCloudflareSandbox({ sandbox, agent, prompt, command, mcp, setting, hook, anthropicKey }, targetDir);
+
+  } else if (sandbox === 'docker') {
+    if (!anthropicKey) {
+      console.log(chalk.red('❌ Error: Anthropic API key is required for Docker sandbox'));
+      console.log(chalk.yellow('💡 Options:'));
+      console.log(chalk.gray('   1. Set environment variable: ANTHROPIC_API_KEY=your_key'));
+      console.log(chalk.gray('   2. Use CLI parameter: --anthropic-api-key your_key'));
+      console.log(chalk.blue('   Get your key at: https://console.anthropic.com'));
+      return;
+    }
+
+    // Execute Docker sandbox
+    await executeDockerSandbox({ sandbox, agent, prompt, command, mcp, setting, hook, anthropicKey, yes: options.yes }, targetDir);
   }
 }
 
@@ -2817,6 +2834,199 @@ async function executeCloudflareSandbox(options, targetDir) {
   }
 }
 
+async function executeDockerSandbox(options, targetDir) {
+  const { agent, command, mcp, setting, hook, prompt, anthropicKey, yes } = options;
+
+  console.log(chalk.blue('\n🐳 Docker Sandbox Execution'));
+  console.log(chalk.cyan('═══════════════════════════════════════'));
+
+  if (agent) {
+    const agentList = agent.split(',');
+    if (agentList.length > 1) {
+      console.log(chalk.white(`📋 Agents (${agentList.length}):`));
+      agentList.forEach(a => console.log(chalk.yellow(`   • ${a.trim()}`)));
+    } else {
+      console.log(chalk.white(`📋 Agent: ${chalk.yellow(agent)}`));
+    }
+  } else {
+    console.log(chalk.white(`📋 Agent: ${chalk.yellow('default')}`));
+  }
+
+  const truncatedPrompt = prompt.length > 80 ? prompt.substring(0, 80) + '...' : prompt;
+  console.log(chalk.white(`💭 Prompt: ${chalk.cyan('"' + truncatedPrompt + '"')}`));
+  console.log(chalk.white(`🐳 Provider: ${chalk.green('Docker Local')}`));
+  console.log(chalk.gray('\n🔧 Execution details:'));
+  console.log(chalk.gray('   • Uses Claude Agent SDK for execution'));
+  console.log(chalk.gray('   • Executes in isolated Docker container'));
+  console.log(chalk.gray('   • Local execution with full filesystem access\n'));
+
+  // Skip confirmation prompt if --yes flag is used
+  if (!yes) {
+    const inquirer = require('inquirer');
+
+    const { shouldExecute } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'shouldExecute',
+      message: 'Execute this prompt in Docker sandbox?',
+      default: true
+    }]);
+
+    if (!shouldExecute) {
+      console.log(chalk.yellow('⏹️  Docker sandbox execution cancelled by user.'));
+      return;
+    }
+  }
+
+  try {
+    console.log(chalk.blue('🔮 Setting up Docker sandbox environment...'));
+
+    const spinner = ora('Installing Docker sandbox component...').start();
+
+    // Create .claude/sandbox/docker directory
+    const sandboxDir = path.join(targetDir, '.claude', 'sandbox', 'docker');
+    await fs.ensureDir(sandboxDir);
+
+    // Copy Docker component files
+    const componentsDir = path.join(__dirname, '..', 'components', 'sandbox', 'docker');
+
+    try {
+      if (await fs.pathExists(componentsDir)) {
+        console.log(chalk.gray('📦 Using local Docker component files...'));
+        console.log(chalk.dim(`   Source: ${componentsDir}`));
+        console.log(chalk.dim(`   Target: ${sandboxDir}`));
+
+        // Copy all files from docker directory
+        await fs.copy(componentsDir, sandboxDir, {
+          overwrite: true
+        });
+
+        // Verify files were copied
+        const copiedFiles = await fs.readdir(sandboxDir);
+        console.log(chalk.dim(`   Copied ${copiedFiles.length} items`));
+        if (copiedFiles.length === 0) {
+          throw new Error('No files were copied from Docker component directory');
+        }
+      } else {
+        throw new Error(`Docker component files not found at: ${componentsDir}`);
+      }
+    } catch (error) {
+      spinner.fail(`Failed to install Docker component: ${error.message}`);
+      throw error;
+    }
+
+    spinner.succeed('Docker sandbox component installed successfully');
+
+    // Check for Docker
+    const dockerSpinner = ora('Checking Docker environment...').start();
+
+    try {
+      const { spawn } = require('child_process');
+
+      // Check Docker installation
+      const checkDocker = () => {
+        return new Promise((resolve) => {
+          const check = spawn('docker', ['--version'], { stdio: 'pipe' });
+          check.on('close', (code) => resolve(code === 0));
+          check.on('error', () => resolve(false));
+        });
+      };
+
+      const dockerAvailable = await checkDocker();
+      if (!dockerAvailable) {
+        dockerSpinner.fail('Docker not found');
+        console.log(chalk.red('❌ Docker is required for Docker sandbox'));
+        console.log(chalk.yellow('💡 Please install Docker and try again'));
+        console.log(chalk.blue('   Visit: https://docs.docker.com/get-docker/'));
+        return;
+      }
+
+      // Check Docker daemon
+      const checkDockerRunning = () => {
+        return new Promise((resolve) => {
+          const check = spawn('docker', ['ps'], { stdio: 'pipe' });
+          check.on('close', (code) => resolve(code === 0));
+          check.on('error', () => resolve(false));
+        });
+      };
+
+      const dockerRunning = await checkDockerRunning();
+      if (!dockerRunning) {
+        dockerSpinner.fail('Docker daemon not running');
+        console.log(chalk.red('❌ Docker daemon is not running'));
+        console.log(chalk.yellow('💡 Please start Docker and try again'));
+        return;
+      }
+
+      dockerSpinner.succeed('Docker environment ready');
+
+      // Build components string for installation inside sandbox
+      let componentsToInstall = '';
+      if (agent) {
+        const agentList = agent.split(',').map(a => `--agent ${a.trim()}`);
+        componentsToInstall += agentList.join(' ');
+      }
+      if (command) {
+        const commandList = command.split(',').map(c => ` --command ${c.trim()}`);
+        componentsToInstall += commandList.join(' ');
+      }
+      if (mcp) {
+        const mcpList = mcp.split(',').map(m => ` --mcp ${m.trim()}`);
+        componentsToInstall += mcpList.join(' ');
+      }
+      if (setting) {
+        const settingList = setting.split(',').map(s => ` --setting ${s.trim()}`);
+        componentsToInstall += settingList.join(' ');
+      }
+      if (hook) {
+        const hookList = hook.split(',').map(h => ` --hook ${h.trim()}`);
+        componentsToInstall += hookList.join(' ');
+      }
+
+      // Execute Docker launcher
+      const execSpinner = ora('Executing Docker sandbox...').start();
+
+      const launcherPath = path.join(sandboxDir, 'docker-launcher.js');
+
+      const dockerExec = spawn('node', [launcherPath, prompt, componentsToInstall.trim()], {
+        cwd: sandboxDir,
+        stdio: 'inherit',
+        env: {
+          ...process.env,
+          ANTHROPIC_API_KEY: anthropicKey
+        }
+      });
+
+      await new Promise((resolve, reject) => {
+        dockerExec.on('close', (dockerCode) => {
+          if (dockerCode === 0) {
+            execSpinner.succeed('Docker sandbox execution completed successfully');
+            console.log(chalk.green('\n✅ Docker sandbox execution finished!'));
+            console.log(chalk.white('📁 Output files are in the output/ directory'));
+            resolve();
+          } else {
+            execSpinner.fail(`Docker sandbox execution failed with code ${dockerCode}`);
+            reject(new Error(`Docker execution failed with code ${dockerCode}`));
+          }
+        });
+
+        dockerExec.on('error', (error) => {
+          execSpinner.fail('Failed to execute Docker sandbox');
+          reject(error);
+        });
+      });
+
+    } catch (error) {
+      dockerSpinner.fail('Failed to check Docker environment');
+      console.log(chalk.red(`❌ Error: ${error.message}`));
+      throw error;
+    }
+
+  } catch (error) {
+    console.log(chalk.red(`❌ Error setting up Docker sandbox: ${error.message}`));
+    console.log(chalk.yellow('💡 Please check your Docker installation and try again'));
+  }
+}
+
 async function executeE2BSandbox(options, targetDir) {
   const { agent, prompt, command, mcp, setting, hook, e2bKey, anthropicKey } = options;