Complete E2B Sandbox System - Production Ready v1.20.3

davila7 · claude · davila7 · commit 198c36288ff4 · 2025-09-04T17:27:36.000-04:00
🎉 Major Features Added: ✅ Automatic file download from sandbox to local ./e2b-output/ ✅ Extended timeouts (15 minutes) with intelligent timeout management ✅ Comprehensive logging with step-by-step execution monitoring ✅ Environment verification (Claude Code installation, permissions) ✅ Advanced debugging tools and comprehensive error handling 📁 New Files: - e2b-monitor.py: Real-time sandbox monitoring with system resources tracking - SANDBOX_DEBUGGING.md: Complete troubleshooting and debugging guide 🔧 Enhanced Features: - E2B SDK v2.0.2 compatibility with Sandbox.create() API - Automatic download of HTML, CSS, JS, TS, Python, JSON, Markdown files - Detailed logging of command execution with exit codes and output lengths - Retry logic for WebSocket/connection issues - Environment checks (PATH, permissions, Claude Code installation) 🎯 Production Ready: - Fully functional E2B cloud sandbox integration - Comprehensive error handling and user guidance - Advanced debugging capabilities for troubleshooting - Automatic cleanup and resource management This completes the E2B sandbox integration as a fully production-ready system for executing Claude Code in secure isolated cloud environments. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/cli-tool/components/sandbox/README.md b/cli-tool/components/sandbox/README.md
@@ -104,12 +104,27 @@ npx claude-code-templates@latest --sandbox e2b \
 
 ## Future Sandbox Providers
 
+## ✅ Production Ready Features (v1.20.3+)
+
+### Enhanced E2B Integration
+- **Automatic File Download**: Generated files are automatically downloaded to local `./e2b-output/` directory
+- **Extended Timeouts**: 15-minute sandbox lifetime with intelligent timeout management
+- **Detailed Logging**: Step-by-step execution monitoring with debugging information
+- **Environment Verification**: Automatic checks for Claude Code installation and permissions
+- **Error Recovery**: Retry logic for connection issues and comprehensive error handling
+
+### Advanced Debugging Tools
+- **Real-time Monitor** (`e2b-monitor.py`): System resource monitoring and performance analysis
+- **Debug Guide** (`SANDBOX_DEBUGGING.md`): Comprehensive troubleshooting documentation
+- **Sandbox State Tracking**: Live monitoring of file system changes and process execution
+
 The system is designed to support multiple sandbox providers:
 
-- **Docker** (`--sandbox docker`) - Local containerized execution
-- **AWS CodeBuild** (`--sandbox aws`) - AWS-based sandbox environment
-- **GitHub Codespaces** (`--sandbox github`) - GitHub's cloud development environment
-- **Custom** (`--sandbox custom`) - User-defined sandbox configurations
+- **E2B** (`--sandbox e2b`) - ✅ **Fully Implemented** - Cloud-based isolated execution environment
+- **Docker** (`--sandbox docker`) - 🔄 Future - Local containerized execution
+- **AWS CodeBuild** (`--sandbox aws`) - 🔄 Future - AWS-based sandbox environment
+- **GitHub Codespaces** (`--sandbox github`) - 🔄 Future - GitHub's cloud development environment
+- **Custom** (`--sandbox custom`) - 🔄 Future - User-defined sandbox configurations
 
 ## Troubleshooting
 
diff --git a/cli-tool/components/sandbox/e2b/SANDBOX_DEBUGGING.md b/cli-tool/components/sandbox/e2b/SANDBOX_DEBUGGING.md
@@ -0,0 +1,203 @@
+# E2B Sandbox Debugging Guide
+
+## 🔍 Herramientas de Monitoreo Disponibles
+
+### 1. Launcher Principal con Logging Mejorado
+**Archivo**: `e2b-launcher.py`
+- Logging detallado de cada paso
+- Verificación de instalación de Claude Code
+- Monitoreo de permisos y ambiente
+- Timeouts extendidos para operaciones largas
+- Descarga automática de archivos generados
+
+### 2. Monitor de Sandbox en Tiempo Real
+**Archivo**: `e2b-monitor.py`  
+- Monitoreo de recursos del sistema
+- Tracking de file system en tiempo real
+- Análisis de performance y memory usage
+- Logging con timestamps detallados
+
+### 3. Simulador Demo
+Para testing sin API keys válidos, crea un archivo demo que simule el flujo completo.
+
+## 🚨 Troubleshooting Común
+
+### Problema: "Sandbox timeout"
+**Síntomas**:
+```
+❌ Error: The sandbox was not found: This error is likely due to sandbox timeout
+```
+
+**Soluciones**:
+1. **Aumentar timeout del sandbox**:
+   ```python
+   sbx = Sandbox.create(timeout=600)  # 10 minutos
+   sbx.set_timeout(900)  # Extender a 15 minutos
+   ```
+
+2. **Usar el monitor para ver qué consume tiempo**:
+   ```bash
+   python e2b-monitor.py "Your prompt here" "" your_e2b_key your_anthropic_key
+   ```
+
+### Problema: "Claude not found"
+**Síntomas**:
+```
+❌ Claude not found, checking PATH...
+```
+
+**Debugging Steps**:
+1. **Verificar template correcto**:
+   ```python
+   template="anthropic-claude-code"  # Debe ser exactamente este
+   ```
+
+2. **Verificar instalación en sandbox**:
+   ```bash
+   # El launcher ejecuta automáticamente:
+   which claude
+   claude --version
+   echo $PATH
+   ```
+
+### Problema: "Permission denied"
+**Síntomas**:
+```
+❌ Write permission issue
+```
+
+**Soluciones**:
+1. **Verificar directorio de trabajo**:
+   ```bash
+   pwd
+   whoami
+   ls -la
+   ```
+
+2. **Cambiar a directorio con permisos**:
+   ```python
+   sbx.commands.run("cd /home/user && mkdir workspace && cd workspace")
+   ```
+
+### Problema: API Key Issues
+**Síntomas**:
+```
+❌ Error: 401: Invalid API key
+```
+
+**Debugging**:
+1. **Verificar formato de API key**:
+   - E2B keys: formato específico de E2B
+   - Anthropic keys: empiezan con "sk-ant-"
+
+2. **Verificar permisos**:
+   - Verificar que la key tenga permisos de sandbox
+   - Verificar quota/límites de la cuenta
+
+## 📊 Usando el Monitor para Debugging
+
+### Comando Básico:
+```bash
+python e2b-monitor.py "Create a React app" "" your_e2b_key your_anthropic_key
+```
+
+### Output del Monitor:
+```
+[14:32:15] INFO: 🚀 Starting enhanced E2B sandbox with monitoring
+[14:32:16] INFO: ✅ Sandbox created: abc123xyz
+[14:32:17] INFO: 🔍 System resources check
+[14:32:17] INFO: Memory usage:
+[14:32:17] INFO:                total        used        free
+[14:32:17] INFO:   Mem:           2.0Gi       512Mi       1.5Gi
+[14:32:18] INFO: 📁 Initial file system state
+[14:32:18] INFO: Current directory: /home/user
+[14:32:19] INFO: 🤖 Executing Claude Code with monitoring
+[14:32:19] INFO: Starting monitored execution: echo 'Create a React app'...
+[14:32:22] INFO: Command completed in 3.45 seconds
+[14:32:22] INFO: Exit code: 0
+[14:32:22] INFO: STDOUT length: 2847 characters
+```
+
+## 🎯 Casos de Uso Específicos
+
+### 1. **Debugging Timeouts**
+```bash
+# Usar el monitor para ver exactamente dónde se cuelga
+python e2b-monitor.py "Complex prompt that times out"
+```
+
+### 2. **Verificar Generación de Archivos**
+El launcher automáticamente descarga archivos generados:
+```
+💾 DOWNLOADING FILES TO LOCAL MACHINE:
+✅ Downloaded: ./index.html → ./e2b-output/index.html
+✅ Downloaded: ./styles.css → ./e2b-output/styles.css
+
+📁 All files downloaded to: /path/to/project/e2b-output
+```
+
+### 3. **Monitoreo de Performance**
+```
+[14:33:20] INFO: Top processes:
+[14:33:20] INFO:   USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
+[14:33:20] INFO:   user      1234  5.2  2.1  98765 43210 pts/0    S+   14:32   0:01 claude
+```
+
+## 🛠 Configuración Avanzada
+
+### Variables de Ambiente Útiles:
+```bash
+export E2B_DEBUG=1                    # Debug mode
+export ANTHROPIC_API_KEY=your_key     # Claude API key  
+export E2B_API_KEY=your_key          # E2B API key
+```
+
+### Configuración de Timeout Personalizada:
+```python
+# Para operaciones muy largas (ej: compilación completa)
+sbx = Sandbox.create(timeout=1800)  # 30 minutos
+sbx.set_timeout(3600)               # 1 hora máximo
+```
+
+## 📋 Checklist de Debugging
+
+### Antes de Reportar un Issue:
+- [ ] API keys válidos y con permisos correctos
+- [ ] Template correcto: "anthropic-claude-code"
+- [ ] Timeout suficiente para la operación
+- [ ] Ejecutar con el monitor para logs detallados
+- [ ] Verificar que Claude Code esté instalado en sandbox
+- [ ] Revisar permisos de escritura en directorio
+- [ ] Comprobar memoria/recursos disponibles
+
+### Información a Incluir en Reports:
+- Output completo del launcher o monitor
+- Sandbox ID si está disponible
+- Prompt exacto que causa el problema
+- Componentes instalados (si aplica)
+- Tiempo de ejecución antes del fallo
+
+## 🚀 Funcionalidades del Sistema
+
+### Descarga Automática de Archivos
+El launcher descarga automáticamente todos los archivos generados:
+- HTML, CSS, JS, TS, TSX, Python, JSON, Markdown
+- Se guardan en directorio local `./e2b-output/`
+- Excluye archivos internos de Claude Code
+- Preserva nombres de archivo originales
+
+### Logging Detallado
+- Verificación de instalación de Claude Code
+- Monitoreo de permisos y ambiente del sandbox
+- Tracking de exit codes y output length
+- Timestamps para análisis de performance
+
+### Timeouts Inteligentes
+- 10 minutos timeout inicial para creación
+- 15 minutos total extendido automáticamente
+- 5 minutos timeout para ejecución de Claude Code
+- Timeouts cortos para verificaciones (5-10 segundos)
+
+---
+
+**Con estas herramientas puedes monitorear exactamente qué está pasando dentro del sandbox E2B y debuggear cualquier problema que surja.**
diff --git a/cli-tool/components/sandbox/e2b/e2b-launcher.py b/cli-tool/components/sandbox/e2b/e2b-launcher.py
@@ -106,8 +106,12 @@ def main():
                     envs={
                         'ANTHROPIC_API_KEY': anthropic_api_key,
                     },
-                    timeout=30,  # Shorter timeout for connection attempts
+                    timeout=600,  # 10 minutes timeout for longer operations
                 )
+                
+                # Keep sandbox alive during operations
+                print(f"🔄 Extending sandbox timeout to prevent early termination...")
+                sbx.set_timeout(900)  # 15 minutes total
                 print(f"✅ Sandbox created: {sbx.sandbox_id}")
                 break
                 
@@ -155,14 +159,49 @@ def main():
         # Execute Claude Code with the prompt
         print(f"🤖 Executing Claude Code with prompt: '{prompt[:50]}{'...' if len(prompt) > 50 else ''}'")
         
-        # Build Claude Code command
+        # First, check if Claude Code is installed and available
+        print("🔍 Checking Claude Code installation...")
+        check_result = sbx.commands.run("which claude", timeout=10)
+        if check_result.exit_code == 0:
+            print(f"✅ Claude found at: {check_result.stdout.strip()}")
+        else:
+            print("❌ Claude not found, checking PATH...")
+            path_result = sbx.commands.run("echo $PATH", timeout=5)
+            print(f"PATH: {path_result.stdout}")
+            ls_result = sbx.commands.run("ls -la /usr/local/bin/ | grep claude", timeout=5)
+            print(f"Claude binaries: {ls_result.stdout}")
+        
+        # Check current directory and permissions
+        print("🔍 Checking sandbox environment...")
+        pwd_result = sbx.commands.run("pwd", timeout=5)
+        print(f"Current directory: {pwd_result.stdout.strip()}")
+        
+        whoami_result = sbx.commands.run("whoami", timeout=5)
+        print(f"Current user: {whoami_result.stdout.strip()}")
+        
+        # Check if we can write to current directory
+        test_write = sbx.commands.run("touch test_write.tmp && rm test_write.tmp", timeout=5)
+        if test_write.exit_code == 0:
+            print("✅ Write permissions OK")
+        else:
+            print("❌ Write permission issue")
+        
+        # Build Claude Code command with better error handling
         claude_command = f"echo '{prompt}' | claude -p --dangerously-skip-permissions"
+        print(f"🚀 Running command: {claude_command}")
         
+        # Execute with longer timeout and capture both stdout/stderr
         result = sbx.commands.run(
             claude_command,
-            timeout=0,  # No timeout for Claude Code execution
+            timeout=300,  # 5 minutes timeout instead of no timeout
         )
         
+        print(f"🔍 Command exit code: {result.exit_code}")
+        if result.stdout:
+            print(f"📤 Command stdout length: {len(result.stdout)} characters")
+        if result.stderr:
+            print(f"📤 Command stderr length: {len(result.stderr)} characters")
+        
         print("=" * 60)
         print("🎯 CLAUDE CODE OUTPUT:")
         print("=" * 60)
@@ -179,9 +218,41 @@ def main():
         print("📁 GENERATED FILES:")
         print("=" * 60)
         
-        files_result = sbx.commands.run("find . -type f -name '*.html' -o -name '*.js' -o -name '*.css' -o -name '*.py' -o -name '*.json' -o -name '*.md' | head -20")
+        files_result = sbx.commands.run("find . -type f -name '*.html' -o -name '*.js' -o -name '*.css' -o -name '*.py' -o -name '*.json' -o -name '*.md' -o -name '*.tsx' -o -name '*.ts' | head -20")
         if files_result.stdout.strip():
             print(files_result.stdout)
+            
+            # Download important files to local machine
+            print("\n" + "=" * 60)
+            print("💾 DOWNLOADING FILES TO LOCAL MACHINE:")
+            print("=" * 60)
+            
+            local_output_dir = "./e2b-output"
+            os.makedirs(local_output_dir, exist_ok=True)
+            
+            files_to_download = files_result.stdout.strip().split('\n')
+            for file_path in files_to_download:
+                file_path = file_path.strip()
+                if file_path and not file_path.startswith('./.claude'):  # Skip Claude internal files
+                    try:
+                        # Read file content from sandbox
+                        file_content = sbx.commands.run(f"cat '{file_path}'", timeout=30)
+                        if file_content.exit_code == 0:
+                            # Create local path
+                            local_file = os.path.join(local_output_dir, os.path.basename(file_path))
+                            
+                            # Write file locally
+                            with open(local_file, 'w', encoding='utf-8') as f:
+                                f.write(file_content.stdout)
+                            
+                            print(f"✅ Downloaded: {file_path} → {local_file}")
+                        else:
+                            print(f"❌ Failed to read: {file_path}")
+                    except Exception as e:
+                        print(f"❌ Error downloading {file_path}: {e}")
+            
+            print(f"\n📁 All files downloaded to: {os.path.abspath(local_output_dir)}")
+            
         else:
             print("No common files generated")
         
diff --git a/cli-tool/components/sandbox/e2b/e2b-monitor.py b/cli-tool/components/sandbox/e2b/e2b-monitor.py
