Deploy Code Execution Sandbox with FastAPI and Docker

.env.example

@@ -0,0 +1,6 @@
+# Environment Configuration
+MAX_EXECUTION_TIME=30
+MAX_MEMORY_MB=512
+ENABLE_NETWORK=false
+LOG_LEVEL=INFO
+MAX_OUTPUT_SIZE=1048576

.gitignore

@@ -0,0 +1,17 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.coverage
+htmlcov/
+.vscode/
+.idea/
+*.log

Dockerfile

@@ -13,4 +13,5 @@ COPY --chown=user ./requirements.txt requirements.txt
 RUN pip install --no-cache-dir --upgrade -r requirements.txt
 
 COPY --chown=user . /app
+
 CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,352 @@
 ---
-title: Isolated Sandbox
+title: Code Execution Sandbox
 emoji: 🏃
 colorFrom: blue
-colorTo: yellow
+colorTo: purple
 sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Code Execution Sandbox API 🚀
+
+A secure, isolated code execution sandbox API built with FastAPI and Docker. Execute Python, JavaScript, and Bash code in ephemeral containers with strict resource limits and security controls.
+
+## ✨ Features
+
+- **Multi-Language Support**: Python, JavaScript (Node.js), and Bash
+- **Security First**: 
+  - Network isolation (no internet access)
+  - Resource limits (CPU, memory, timeout)
+  - Read-only filesystem
+  - Non-root user execution
+- **Automatic Cleanup**: Containers are destroyed after each execution
+- **RESTful API**: Simple JSON-based interface
+- **Resource Management**: Configurable CPU, memory, and execution timeouts
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Docker** installed and running
+- **Python 3.9+**
+
+### Installation
+
+1. **Clone the repository**:
+```bash
+git clone https://huggingface.co/spaces/fariasultanacodes/isolated-sandbox
+cd isolated-sandbox
+```
+
+2. **Install dependencies**:
+```bash
+pip install -r requirements.txt
+```
+
+3. **Run the API**:
+```bash
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+The API will be available at `http://localhost:7860`
+
+## 📡 API Endpoints
+
+### `POST /execute`
+
+Execute code in an isolated sandbox.
+
+**Request Body**:
+```json
+{
+  "code": "print('Hello, World!')",
+  "language": "python",
+  "stdin": "",
+  "timeout": 10,
+  "memory_limit": 256
+}
+```
+
+**Response**:
+```json
+{
+  "stdout": "Hello, World!\n",
+  "stderr": "",
+  "exit_code": 0,
+  "execution_time": 0.123,
+  "error": null
+}
+```
+
+**Parameters**:
+- `code` (string, required): Code to execute
+- `language` (enum, required): `"python"`, `"javascript"`, or `"bash"`
+- `stdin` (string, optional): Standard input for the code
+- `timeout` (integer, optional): Execution timeout in seconds (1-30, default: 10)
+- `memory_limit` (integer, optional): Memory limit in MB (64-512, default: 256)
+
+### `GET /languages`
+
+List all supported programming languages.
+
+**Response**:
+```json
+{
+  "languages": [
+    {
+      "name": "Python",
+      "version": "3.11",
+      "image": "python:3.11-slim",
+      "extensions": [".py"]
+    },
+    ...
+  ]
+}
+```
+
+### `GET /health`
+
+Health check endpoint.
+
+**Response**:
+```json
+{
+  "status": "healthy",
+  "docker": "connected"
+}
+```
+
+## 💡 Usage Examples
+
+### Python Execution
+
+```bash
+curl -X POST http://localhost:7860/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "code": "for i in range(5):\n    print(f\"Count: {i}\")",
+    "language": "python"
+  }'
+```
+
+### JavaScript Execution
+
+```bash
+curl -X POST http://localhost:7860/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "code": "const arr = [1, 2, 3, 4, 5];\nconsole.log(arr.reduce((a, b) => a + b));",
+    "language": "javascript"
+  }'
+```
+
+### Bash Execution
+
+```bash
+curl -X POST http://localhost:7860/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "code": "echo \"System Info:\"; uname -a",
+    "language": "bash"
+  }'
+```
+
+### With Timeout
+
+```bash
+curl -X POST http://localhost:7860/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "code": "import time\ntime.sleep(5)\nprint(\"Done!\")",
+    "language": "python",
+    "timeout": 2
+  }'
+```
+
+## 🔒 Security Features
+
+1. **Network Isolation**: Containers run with `network_mode="none"`, preventing internet access
+2. **Resource Limits**:
+   - CPU: Limited to 0.5 cores
+   - Memory: Configurable (64-512 MB)
+   - Timeout: Configurable (1-30 seconds)
+   - PIDs: Limited to 50 processes
+3. **Filesystem**: Read-only root filesystem (except `/tmp`)
+4. **User Privileges**: Code runs as non-root user (`nobody`)
+5. **Output Limits**: Stdout/stderr truncated at 1MB to prevent memory attacks
+6. **Automatic Cleanup**: Containers are removed immediately after execution
+
+## ⚙️ Configuration
+
+Create a `.env` file based on `.env.example`:
+
+```bash
+MAX_EXECUTION_TIME=30
+MAX_MEMORY_MB=512
+ENABLE_NETWORK=false
+LOG_LEVEL=INFO
+MAX_OUTPUT_SIZE=1048576
+```
+
+# Custom Docker Images
+
+The sandbox uses pre-built, hardened Docker images for each language:
+
+### Python Image
+```dockerfile
+FROM python:3.11-slim-alpine
+# Custom Python sandbox image with security hardening
+```
+Location: `sandbox/images/python.Dockerfile`
+
+### JavaScript Image
+```dockerfile
+FROM node:20-alpine
+# Custom Node.js sandbox image with security hardening
+```
+Location: `sandbox/images/javascript.Dockerfile`
+
+### Bash Image
+```dockerfile
+FROM bash:5.2-alpine
+# Custom Bash sandbox image with security hardening
+```
+Location: `sandbox/images/bash.Dockerfile`
+
+**Benefits**:
+- Smaller image sizes (Alpine Linux base)
+- Security hardened with non-root users
+- Minimal attack surface
+- Faster container startup times
+
+You can build these images locally if needed:
+```bash
+# Build Python sandbox image
+docker build -t sandbox-python:latest -f sandbox/images/python.Dockerfile sandbox/images/
+
+# Build JavaScript sandbox image
+docker build -t sandbox-javascript:latest -f sandbox/images/javascript.Dockerfile sandbox/images/
+
+# Build Bash sandbox image
+docker build -t sandbox-bash:latest -f sandbox/images/bash.Dockerfile sandbox/images/
+```
+
+## 🐳 Docker Deployment
+
+### Option 1: Self-Hosted
+
+The application requires access to the Docker daemon. Run with Docker socket mounted:
+
+```bash
+docker build -t code-sandbox .
+docker run -d \
+  -p 7860:7860 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  --name code-sandbox \
+  code-sandbox
+```
+
+### Option 2: Cloud Platforms
+
+Deploy to platforms with Docker support:
+- **Modal**: Use Modal's container runtime
+- **Fly.io**: Deploy with Docker support
+- **Railway**: Deploy with Docker socket access
+- **Render**: Deploy with Docker enabled
+
+> **Note**: Hugging Face Spaces does not support Docker-in-Docker, so this requires self-hosting or alternative platforms.
+
+## 📝 Examples
+
+Check the `examples/` directory for sample code in multiple languages:
+
+### Python Examples
+- `examples/hello_world.py` - Simple hello world
+- `examples/python_stdin.py` - Input/output and calculations
+- `examples/python_classes.py` - Object-oriented programming
+- `examples/python_data.py` - Data processing and algorithms
+
+### JavaScript Examples
+- `examples/hello_world.js` - Simple hello world
+- `examples/javascript_arrays.js` - Array operations and functions
+- `examples/javascript_objects.js` - Objects and classes
+
+### Bash Examples
+- `examples/hello_world.sh` - Simple hello world
+- `examples/bash_system_info.sh` - System information display
+- `examples/bash_loops.sh` - Loop operations and functions
+
+## 🛠️ Development
+
+### Run Tests
+
+```bash
+# Install dev dependencies
+pip install pytest pytest-asyncio httpx
+
+# Run tests
+pytest tests/ -v
+```
+
+### Local Development
+
+```bash
+# Run with hot reload
+uvicorn app:app --reload --host 0.0.0.0 --port 7860
+```
+
+## 📊 Architecture
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │ HTTP POST /execute
+       ▼
+┌─────────────────┐
+│  FastAPI App    │
+│   (app.py)      │
+└──────┬──────────┘
+       │
+       ▼
+┌─────────────────┐
+│ SandboxExecutor │
+│  (executor.py)  │
+└──────┬──────────┘
+       │ Docker SDK
+       ▼
+┌─────────────────┐
+│ Ephemeral       │
+│ Container       │
+│ (Python/JS/Bash)│
+└─────────────────┘
+       │
+       ▼ (cleanup)
+     ♻️ Removed
+```
+
+## ⚠️ Important Notes
+
+1. **Rate Limiting**: For production use, implement rate limiting to prevent abuse
+2. **Authentication**: Add authentication for public deployments
+3. **Monitoring**: Monitor Docker resource usage and container counts
+4. **Resource Costs**: Each execution creates a new container; consider costs at scale
+5. **Docker Requirement**: The host system must have Docker installed and accessible
+
+## 📄 License
+
+This project is open-source and available under the MIT License.
+
+## 🤝 Contributing
+
+Contributions welcome! Please feel free to submit issues or pull requests.
+
+## 🔗 Links
+
+- [Hugging Face Space](https://huggingface.co/spaces/fariasultanacodes/isolated-sandbox)
+- [Docker Documentation](https://docs.docker.com/)
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+
+---
+
+**Built with ❤️ using FastAPI and Docker**

app.py

@@ -1,7 +1,530 @@
-from fastapi import FastAPI
+from fastapi import FastAPI, HTTPException, status, UploadFile, File, Path as FastAPIPath
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, Response
+import logging
+from contextlib import asynccontextmanager
+from typing import List
+
+from sandbox.executor import SandboxExecutor
+from sandbox.session_manager import SessionManager
+from sandbox.file_manager import FileManager
+from sandbox.container_builder import ContainerBuilder
+from sandbox.models import (
+    ExecutionRequest, ExecutionResponse, SandboxConfig, Language,
+    CreateSessionRequest, SessionResponse, FileInfo, FileUploadResponse,
+    ExecuteInSessionRequest, ExecuteFileRequest
+)
+from sandbox.language_runners import LanguageRunner
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Global instances
+executor: SandboxExecutor = None
+session_manager: SessionManager = None
+file_manager: FileManager = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize and cleanup resources"""
+    global executor, session_manager, file_manager
+    try:
+        # Build/verify devenv image
+        logger.info("Checking development environment image...")
+        builder = ContainerBuilder()
+        if not builder.ensure_devenv_image():
+            logger.warning("Dev environment image not available, sessions will fail")
+        
+        # Initialize services
+        logger.info("Initializing sandbox services...")
+        executor = SandboxExecutor(SandboxConfig())
+        session_manager = SessionManager(SandboxConfig())
+        file_manager = FileManager()
+        logger.info("All services initialized successfully")
+        yield
+    except Exception as e:
+        logger.error(f"Failed to initialize services: {e}")
+        raise
+    finally:
+        # Cleanup on shutdown
+        if session_manager:
+            logger.info("Shutting down session manager...")
+            session_manager.shutdown()
+
+
+app = FastAPI(
+    title="Code Execution Sandbox API",
+    description="Execute code in isolated containers with persistent VM-like sessions and file system operations",
+    version="2.0.0",
+    lifespan=lifespan
+)
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
 
-app = FastAPI()
 
 @app.get("/")
-def greet_json():
-    return {"Hello": "World!"}
+def root():
+    """Root endpoint with API information"""
+    return {
+        "name": "Code Execution Sandbox API",
+        "version": "2.0.0",
+        "status": "running",
+        "features": {
+            "stateless_execution": "/execute",
+            "persistent_sessions": "/sessions",
+            "file_operations": True,
+            "multi_language": True
+        },
+        "supported_languages": ["python", "javascript", "bash"],
+        "endpoints": {
+            "execute": "/execute (stateless)",
+            "sessions": "/sessions (create/list)",
+            "session_detail": "/sessions/{session_id}",
+            "files": "/sessions/{session_id}/files",
+            "execute_in_session": "/sessions/{session_id}/execute",
+            "languages": "/languages",
+            "health": "/health"
+        }
+    }
+
+
+@app.get("/health")
+def health_check():
+    """Health check endpoint"""
+    try:
+        if executor and executor.client:
+            executor.client.ping()
+            
+            # Check session manager
+            session_count = len(session_manager.sessions) if session_manager else 0
+            
+            return {
+                "status": "healthy",
+                "docker": "connected",
+                "active_sessions": session_count
+            }
+    except Exception as e:
+        logger.error(f"Health check failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Service unhealthy: {str(e)}"
+        )
+
+
+@app.get("/languages")
+def list_languages():
+    """List all supported programming languages"""
+    return {
+        "languages": LanguageRunner.get_all_languages()
+    }
+
+
+# ========== Stateless Execution (backward compatible) ==========
+
+@app.post("/execute", response_model=ExecutionResponse)
+def execute_code(request: ExecutionRequest):
+    """
+    Execute code in an isolated ephemeral container (stateless).
+    
+    This is the original execution method - creates a fresh container,
+    executes code, and destroys the container immediately.
+    """
+    if not executor:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Sandbox executor not initialized"
+        )
+    
+    try:
+        logger.info(f"Stateless execution: {request.language} code")
+        result = executor.execute(request)
+        return result
+    except Exception as e:
+        logger.error(f"Execution failed: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Execution failed: {str(e)}"
+        )
+
+
+# ========== Session Management ==========
+
+@app.post("/sessions", response_model=SessionResponse, status_code=status.HTTP_201_CREATED)
+def create_session(request: CreateSessionRequest):
+    """
+    Create a new persistent VM-like session.
+    
+    The session is a long-running container with persistent storage,
+    supporting file uploads and multiple code executions.
+    """
+    if not session_manager:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Session manager not initialized"
+        )
+    
+    try:
+        logger.info(f"Creating new session with metadata: {request.metadata}")
+        session = session_manager.create_session(request)
+        return session
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=str(e)
+        )
+
+
+@app.get("/sessions", response_model=List[SessionResponse])
+def list_sessions():
+    """List all active sessions"""
+    if not session_manager:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Session manager not initialized"
+        )
+    
+    sessions = session_manager.list_sessions()
+    return sessions
+
+
+@app.get("/sessions/{session_id}", response_model=SessionResponse)
+def get_session(session_id: str = FastAPIPath(..., description="Session ID")):
+    """Get session details by ID"""
+    if not session_manager:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Session manager not initialized"
+        )
+    
+    session = session_manager.get_session(session_id)
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found"
+        )
+    
+    # Update file count
+    if file_manager:
+        try:
+            files = file_manager.list_files(session.container_id)
+            session.files_count = len(files)
+        except:
+            pass
+    
+    return session
+
+
+@app.delete("/sessions/{session_id}")
+def destroy_session(session_id: str = FastAPIPath(..., description="Session ID")):
+    """Destroy a session and cleanup all resources"""
+    if not session_manager:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Session manager not initialized"
+        )
+    
+    success = session_manager.destroy_session(session_id)
+    if not success:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found"
+        )
+    
+    return {"message": f"Session {session_id} destroyed successfully"}
+
+
+# ========== File Operations ==========
+
+@app.post("/sessions/{session_id}/files", response_model=FileUploadResponse)
+async def upload_file(
+    session_id: str = FastAPIPath(..., description="Session ID"),
+    file: UploadFile = File(..., description="File to upload")
+):
+    """Upload a file to session workspace"""
+    if not session_manager or not file_manager:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Services not initialized"
+        )
+    
+    # Get session
+    session = session_manager.get_session(session_id)
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found"
+        )
+    
+    try:
+        # Read file data
+        file_data = await file.read()
+        
+        # Upload to container
+        result = file_manager.upload_file(
+            container_id=session.container_id,
+            filename=file.filename,
+            file_data=file_data
+        )
+        
+        # Update session activity
+        session_manager.update_activity(session_id)
+        
+        return result
+        
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+    except Exception as e:
+        logger.error(f"File upload failed: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"File upload failed: {str(e)}"
+        )
+
+
+@app.get("/sessions/{session_id}/files", response_model=List[FileInfo])
+def list_files(session_id: str = FastAPIPath(..., description="Session ID")):
+    """List files in session workspace"""
+    if not session_manager or not file_manager:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Services not initialized"
+        )
+    
+    # Get session
+    session = session_manager.get_session(session_id)
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found"
+        )
+    
+    try:
+        files = file_manager.list_files(session.container_id)
+        return files
+    except Exception as e:
+        logger.error(f"File listing failed: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"File listing failed: {str(e)}"
+        )
+
+
+@app.get("/sessions/{session_id}/files/{filepath:path}")
+def download_file(
+    session_id: str = FastAPIPath(..., description="Session ID"),
+    filepath: str = FastAPIPath(..., description="File path relative to workspace")
+):
+    """Download a file from session workspace"""
+    if not session_manager or not file_manager:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Services not initialized"
+        )
+    
+    # Get session
+    session = session_manager.get_session(session_id)
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found"
+        )
+    
+    try:
+        file_data = file_manager.download_file(session.container_id, filepath)
+        
+        # Determine content type
+        import mimetypes
+        content_type, _ = mimetypes.guess_type(filepath)
+        
+        return Response(
+            content=file_data,
+            media_type=content_type or "application/octet-stream",
+            headers={
+                "Content-Disposition": f"attachment; filename={filepath.split('/')[-1]}"
+            }
+        )
+        
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e)
+        )
+    except Exception as e:
+        logger.error(f"File download failed: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"File download failed: {str(e)}"
+        )
+
+
+# ========== Execute in Session ==========
+
+@app.post("/sessions/{session_id}/execute", response_model=ExecutionResponse)
+def execute_in_session(
+    session_id: str = FastAPIPath(..., description="Session ID"),
+    request: ExecuteInSessionRequest = None
+):
+    """Execute code in an existing session (persistent state)"""
+    if not session_manager:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Session manager not initialized"
+        )
+    
+    # Get session
+    session = session_manager.get_session(session_id)
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found"
+        )
+    
+    try:
+        import time
+        from docker.errors import DockerException
+        
+        container = executor.client.containers.get(session.container_id)
+        runner_config = LanguageRunner.get_runner_config(request.language)
+        
+        start_time = time.time()
+        
+        # Execute command in running container
+        exec_result = container.exec_run(
+            cmd=runner_config["command"] + [request.code],
+            workdir=request.working_dir,
+            demux=True,
+            stream=False
+        )
+        
+        execution_time = time.time() - start_time
+        
+        # Parse output
+        stdout = exec_result.output[0].decode('utf-8', errors='replace') if exec_result.output[0] else ""
+        stderr = exec_result.output[1].decode('utf-8', errors='replace') if exec_result.output[1] else ""
+        
+        # Update session activity
+        session_manager.update_activity(session_id)
+        
+        return ExecutionResponse(
+            stdout=stdout,
+            stderr=stderr,
+            exit_code=exec_result.exit_code,
+            execution_time=round(execution_time, 3),
+            error=None if exec_result.exit_code == 0 else "Execution failed"
+        )
+        
+    except DockerException as e:
+        logger.error(f"Docker error: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Execution failed: {str(e)}"
+        )
+
+
+@app.post("/sessions/{session_id}/execute-file", response_model=ExecutionResponse)
+def execute_file_in_session(
+    session_id: str = FastAPIPath(..., description="Session ID"),
+    request: ExecuteFileRequest = None
+):
+    """Execute an uploaded file in session"""
+    if not session_manager:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Session manager not initialized"
+        )
+    
+    # Get session
+    session = session_manager.get_session(session_id)
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found"
+        )
+    
+    try:
+        import time
+        container = executor.client.containers.get(session.container_id)
+        runner_config = LanguageRunner.get_runner_config(request.language)
+        
+        # Build command based on language
+        if request.language == Language.PYTHON:
+            cmd = ["python", request.filepath] + request.args
+        elif request.language == Language.JAVASCRIPT:
+            cmd = ["node", request.filepath] + request.args
+        elif request.language == Language.BASH:
+            cmd = ["bash", request.filepath] + request.args
+        else:
+            cmd = runner_config["command"] + [request.filepath] + request.args
+        
+        start_time = time.time()
+        
+        # Execute file
+        exec_result = container.exec_run(
+            cmd=cmd,
+            workdir="/workspace",
+            demux=True,
+            stream=False
+        )
+        
+        execution_time = time.time() - start_time
+        
+        # Parse output
+        stdout = exec_result.output[0].decode('utf-8', errors='replace') if exec_result.output[0] else ""
+        stderr = exec_result.output[1].decode('utf-8', errors='replace') if exec_result.output[1] else ""
+        
+        # Update session activity
+        session_manager.update_activity(session_id)
+        
+        return ExecutionResponse(
+            stdout=stdout,
+            stderr=stderr,
+            exit_code=exec_result.exit_code,
+            execution_time=round(execution_time, 3),
+            error=None if exec_result.exit_code == 0 else "Execution failed"
+        )
+        
+    except Exception as e:
+        logger.error(f"File execution failed: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"File execution failed: {str(e)}"
+        )
+
+
+@app.exception_handler(Exception)
+async def global_exception_handler( request, exc):
+    """Global exception handler"""
+    logger.error(f"Unhandled exception: {exc}", exc_info=True)
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content={
+            "error": "Internal server error",
+            "detail": str(exc)
+        }
+    )
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "app:app",
+        host="0.0.0.0",
+        port=7860,
+        reload=False,
+        log_level="info"
+    )

examples/bash_loops.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Bash Example: Loop and Array Processing
+echo "=== Bash Scripting Examples ==="
+echo
+
+# Array of numbers
+numbers=(1 2 3 4 5 6 7 8 9 10)
+
+# Calculate sum using loop
+sum=0
+for num in "${numbers[@]}"; do
+    sum=$((sum + num))
+done
+
+echo "Array: ${numbers[*]}"
+echo "Sum of numbers: $sum"
+echo "Average: $((sum / ${#numbers[@]}))"
+echo
+
+# Find even numbers
+echo "Even numbers:"
+for num in "${numbers[@]}"; do
+    if [ $((num % 2)) -eq 0 ]; then
+        echo "  $num"
+    fi
+done
+echo
+
+# Create a simple counter
+count=1
+while [ $count -le 5 ]; do
+    echo "Count: $count"
+    count=$((count + 1))
+done
+echo
+
+# Function example
+greet() {
+    local name=$1
+    echo "Hello, $name! Welcome to bash scripting."
+}
+
+greet "Alice"
+greet "Bob"

examples/bash_system_info.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Bash Example: System Information
+echo "=== System Information ==="
+echo
+
+# Display basic system info
+echo "Hostname: $(hostname)"
+echo "Current user: $(whoami)"
+echo "Current directory: $(pwd)"
+echo "Current time: $(date)"
+echo
+
+# Display system resources
+echo "Memory usage:"
+free -h
+echo
+
+echo "Disk usage:"
+df -h / | tail -1
+echo
+
+# Display OS information
+echo "Operating System:"
+cat /etc/os-release | grep PRETTY_NAME
+echo
+
+# Process information
+echo "Number of running processes: $(ps aux | wc -l)"
+echo "Current shell: $SHELL"

examples/hello_world.js

@@ -0,0 +1,2 @@
+// Example: Hello World in JavaScript
+console.log("Hello, World!");

examples/hello_world.py

@@ -0,0 +1,2 @@
+# Example: Hello World in Python
+print("Hello, World!")

examples/hello_world.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+# Example: Hello World in Bash
+echo "Hello, World!"

examples/javascript_arrays.js

@@ -0,0 +1,25 @@
+// JavaScript Example: Array Processing and Functions
+const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+// Calculate sum of all numbers
+const sum = numbers.reduce((acc, num) => acc + num, 0);
+console.log(`Sum of numbers: ${sum}`);
+
+// Find even numbers
+const evenNumbers = numbers.filter(num => num % 2 === 0);
+console.log(`Even numbers: ${evenNumbers.join(', ')}`);
+
+// Calculate square of each number
+const squares = numbers.map(num => num * num);
+console.log(`Squares: ${squares.join(', ')}`);
+
+// Fibonacci sequence
+function fibonacci(n) {
+    if (n <= 1) return n;
+    return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+console.log('\nFirst 10 Fibonacci numbers:');
+for (let i = 0; i < 10; i++) {
+    console.log(fibonacci(i));
+}

examples/javascript_objects.js

@@ -0,0 +1,50 @@
+// JavaScript Example: Objects and Classes
+class Calculator {
+    constructor() {
+        this.history = [];
+    }
+    
+    add(a, b) {
+        const result = a + b;
+        this.history.push(`${a} + ${b} = ${result}`);
+        return result;
+    }
+    
+    multiply(a, b) {
+        const result = a * b;
+        this.history.push(`${a} * ${b} = ${result}`);
+        return result;
+    }
+    
+    showHistory() {
+        console.log('Calculation History:');
+        this.history.forEach(entry => console.log(entry));
+    }
+}
+
+// Create calculator instance
+const calc = new Calculator();
+
+// Perform calculations
+console.log('10 + 5 =', calc.add(10, 5));
+console.log('10 * 5 =', calc.multiply(10, 5));
+console.log('7 * 8 =', calc.multiply(7, 8));
+
+// Show history
+calc.showHistory();
+
+// Object with methods
+const person = {
+    name: 'Alice',
+    age: 30,
+    greet() {
+        return `Hello, I'm ${this.name} and I'm ${this.age} years old.`;
+    },
+    haveBirthday() {
+        this.age++;
+    }
+};
+
+console.log(person.greet());
+person.haveBirthday();
+console.log(person.greet());

examples/python_classes.py

@@ -0,0 +1,42 @@
+# Python Example: Classes and Object-Oriented Programming
+class BankAccount:
+    def __init__(self, owner, balance=0):
+        self.owner = owner
+        self.balance = balance
+        self.transactions = []
+    
+    def deposit(self, amount):
+        if amount > 0:
+            self.balance += amount
+            self.transactions.append(f"Deposited: ${amount}")
+            return True
+        return False
+    
+    def withdraw(self, amount):
+        if amount <= self.balance and amount > 0:
+            self.balance -= amount
+            self.transactions.append(f"Withdrew: ${amount}")
+            return True
+        return False
+    
+    def get_balance(self):
+        return f"${self.balance}"
+    
+    def show_transactions(self):
+        print(f"Transaction history for {self.owner}:")
+        for transaction in self.transactions:
+            print(f"  - {transaction}")
+
+# Create account
+account = BankAccount("John Doe", 1000)
+
+print(f"Account created for {account.owner}")
+print(f"Initial balance: {account.get_balance()}")
+
+# Perform transactions
+account.deposit(500)
+account.withdraw(200)
+account.deposit(100)
+
+print(f"Current balance: {account.get_balance()}")
+account.show_transactions()

examples/python_data.py

@@ -0,0 +1,41 @@
+# Python Example: Data Processing and File Operations
+import json
+
+# Sample data
+data = [
+    {"name": "Alice", "age": 25, "city": "New York"},
+    {"name": "Bob", "age": 30, "city": "San Francisco"},
+    {"name": "Charlie", "age": 35, "city": "Boston"},
+    {"name": "Diana", "age": 28, "city": "Chicago"},
+    {"name": "Eve", "age": 22, "city": "New York"}
+]
+
+print("=== Data Processing Demo ===\n")
+
+# Filter people over 27
+older_people = [person for person in data if person["age"] > 27]
+print(f"People over 27: {len(older_people)}")
+
+# Group by city
+cities = {}
+for person in data:
+    city = person["city"]
+    if city not in cities:
+        cities[city] = []
+    cities[city].append(person)
+
+print("\nPeople by city:")
+for city, people in cities.items():
+    print(f"  {city}: {len(people)} people")
+
+# Calculate average age
+total_age = sum(person["age"] for person in data)
+avg_age = total_age / len(data)
+print(f"\nAverage age: {avg_age:.2f}")
+
+# Find youngest and oldest
+youngest = min(data, key=lambda x: x["age"])
+oldest = max(data, key=lambda x: x["age"])
+
+print(f"Youngest: {youngest['name']} ({youngest['age']})")
+print(f"Oldest: {oldest['name']} ({oldest['age']})")

examples/python_stdin.py

@@ -0,0 +1,14 @@
+# Python Example: Input and Output
+name = input("What is your name? ")
+age = int(input("How old are you? "))
+
+print(f"Hello {name}!")
+print(f"You will be {age + 1} next year!")
+
+# Calculate factorial
+def factorial(n):
+    if n <= 1:
+        return 1
+    return n * factorial(n - 1)
+
+print(f"Factorial of {age} is {factorial(age)}")

requirements-dev.txt

@@ -0,0 +1,3 @@
+pytest
+pytest-asyncio
+httpx

requirements.txt

@@ -1,2 +1,7 @@
 fastapi
-uvicorn[standard]
+uvicorn[standard]
+docker
+pydantic
+pydantic-settings
+python-multipart
+aiofiles

sandbox/__init__.py

@@ -0,0 +1 @@
+# Sandbox package for isolated code execution

sandbox/container_builder.py

@@ -0,0 +1,84 @@
+import docker
+from docker.errors import DockerException, ImageNotFound
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class ContainerBuilder:
+    """Builds and manages the development environment Docker image"""
+    
+    IMAGE_NAME = "sandbox-devenv"
+    IMAGE_TAG = "latest"
+    
+    def __init__(self):
+        try:
+            self.client = docker.from_env()
+            logger.info("Container builder initialized")
+        except DockerException as e:
+            logger.error(f"Failed to initialize Docker client: {e}")
+            raise RuntimeError("Docker is not available") from e
+    
+    def image_exists(self) -> bool:
+        """Check if devenv image exists"""
+        try:
+            self.client.images.get(f"{self.IMAGE_NAME}:{self.IMAGE_TAG}")
+            return True
+        except ImageNotFound:
+            return False
+    
+    def build_devenv_image(self) -> bool:
+        """
+        Build the development environment image.
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            dockerfile_path = Path(__file__).parent / "images" / "devenv.Dockerfile"
+            
+            if not dockerfile_path.exists():
+                logger.error(f"Dockerfile not found: {dockerfile_path}")
+                return False
+            
+            logger.info("Building development environment image (this may take several minutes)...")
+            
+            # Build image
+            image, build_logs = self.client.images.build(
+                path=str(dockerfile_path.parent),
+                dockerfile=str(dockerfile_path.name),
+                tag=f"{self.IMAGE_NAME}:{self.IMAGE_TAG}",
+                rm=True,  # Remove intermediate containers
+                pull=True,  # Pull base image
+                decode=True  # Decode build logs
+            )
+            
+            # Print build progress
+            for log in build_logs:
+                if 'stream' in log:
+                    print(log['stream'], end='')
+                elif 'error' in log:
+                    logger.error(f"Build error: {log['error']}")
+                    return False
+            
+            logger.info(f"Successfully built {self.IMAGE_NAME}:{self.IMAGE_TAG}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to build image: {e}", exc_info=True)
+            return False
+    
+    def ensure_devenv_image(self) -> bool:
+        """
+        Ensure devenv image exists, build if necessary.
+        
+        Returns:
+            True if image is available, False otherwise
+        """
+        if self.image_exists():
+            logger.info(f"Image {self.IMAGE_NAME}:{self.IMAGE_TAG} already exists")
+            return True
+        
+        logger.info(f"Image {self.IMAGE_NAME}:{self.IMAGE_TAG} not found, building...")
+        return self.build_devenv_image()

sandbox/executor.py

@@ -0,0 +1,220 @@
+import docker
+from docker.errors import DockerException, ContainerError, ImageNotFound, APIError
+import time
+import logging
+from typing import Optional
+from sandbox.models import ExecutionRequest, ExecutionResponse, SandboxConfig, Language
+from sandbox.language_runners import LanguageRunner
+
+logger = logging.getLogger(__name__)
+
+
+class SandboxExecutor:
+    """
+    Executes code in isolated Docker containers with security controls.
+    
+    Features:
+    - Resource limits (CPU, memory)
+    - Network isolation
+    - Automatic cleanup
+    - Timeout enforcement
+    - Read-only filesystem
+    """
+    
+    def __init__(self, config: Optional[SandboxConfig] = None):
+        self.config = config or SandboxConfig()
+        try:
+            self.client = docker.from_env()
+            # Test Docker connection
+            self.client.ping()
+            logger.info("Docker client initialized successfully")
+        except DockerException as e:
+            logger.error(f"Failed to initialize Docker client: {e}")
+            raise RuntimeError(
+                "Docker is not available. Please ensure Docker is running and accessible."
+            ) from e
+    
+    def _prepare_container_config(
+        self, 
+        request: ExecutionRequest,
+        runner_config: dict
+    ) -> dict:
+        """Prepare Docker container configuration with security settings"""
+        
+        # Calculate resource limits
+        memory_limit = f"{request.memory_limit}m"
+        cpu_quota = 50000  # 0.5 CPU cores (out of 100000)
+        
+        container_config = {
+            "image": runner_config["image"],
+            "command": runner_config["command"] + [request.code],
+            "stdin_open": bool(request.stdin),
+            "detach": True,
+            "remove": False,  # We'll remove manually after getting logs
+            
+            # Security settings
+            "network_mode": "none" if not self.config.enable_network else "bridge",
+            "read_only": self.config.read_only_root,
+            "security_opt": ["no-new-privileges"],
+            
+            # Resource limits
+            "mem_limit": memory_limit,
+            "memswap_limit": memory_limit,  # Disable swap
+            "cpu_quota": cpu_quota,
+            "cpu_period": 100000,
+            
+            # Prevent fork bombs
+            "pids_limit": 50,
+            
+            # Working directory
+            "working_dir": "/tmp",
+            
+            # User (non-root when possible)
+            "user": "nobody" if runner_config["image"] != "bash:5.2-alpine" else None,
+        }
+        
+        return container_config
+    
+    def execute(self, request: ExecutionRequest) -> ExecutionResponse:
+        """
+        Execute code in an isolated container.
+        
+        Args:
+            request: Execution request with code and parameters
+            
+        Returns:
+            ExecutionResponse with stdout, stderr, and execution metadata
+        """
+        start_time = time.time()
+        container = None
+        
+        try:
+            # Get language-specific configuration
+            runner_config = LanguageRunner.get_runner_config(request.language)
+            
+            # Prepare container configuration
+            container_config = self._prepare_container_config(request, runner_config)
+            
+            # Pull image if not available
+            try:
+                self.client.images.get(runner_config["image"])
+            except ImageNotFound:
+                logger.info(f"Pulling image {runner_config['image']}...")
+                self.client.images.pull(runner_config["image"])
+            
+            # Create and start container
+            logger.info(f"Executing {request.language} code in container")
+            container = self.client.containers.create(**container_config)
+            container.start()
+            
+            # Provide stdin if specified
+            if request.stdin:
+                sock = container.attach_socket(params={'stdin': 1, 'stream': 1})
+                sock._sock.sendall(request.stdin.encode())
+                sock.close()
+            
+            # Wait for container to finish with timeout
+            try:
+                result = container.wait(timeout=request.timeout)
+                exit_code = result.get("StatusCode", -1)
+                error_msg = None
+            except Exception as e:
+                # Timeout or other error
+                logger.warning(f"Container execution timeout or error: {e}")
+                container.stop(timeout=1)
+                exit_code = 124  # Timeout exit code
+                error_msg = f"Execution timed out after {request.timeout} seconds"
+            
+            # Get logs (stdout and stderr combined)
+            try:
+                logs = container.logs(stdout=True, stderr=True).decode('utf-8', errors='replace')
+                
+                # Truncate if too large
+                if len(logs) > self.config.max_output_size:
+                    logs = logs[:self.config.max_output_size] + "\n... (output truncated)"
+                
+                # Try to separate stdout and stderr (Docker combines them)
+                stdout = logs
+                stderr = ""
+                
+                # If there's an error, try to extract stderr
+                if exit_code != 0:
+                    stderr = logs
+                    stdout = ""
+                    
+            except Exception as e:
+                logger.error(f"Failed to get container logs: {e}")
+                stdout = ""
+                stderr = str(e)
+            
+            execution_time = time.time() - start_time
+            
+            return ExecutionResponse(
+                stdout=stdout,
+                stderr=stderr,
+                exit_code=exit_code,
+                execution_time=round(execution_time, 3),
+                error=error_msg
+            )
+            
+        except ImageNotFound as e:
+            logger.error(f"Image not found: {e}")
+            return ExecutionResponse(
+                stdout="",
+                stderr="",
+                exit_code=-1,
+                execution_time=time.time() - start_time,
+                error=f"Language image not available: {runner_config['image']}"
+            )
+            
+        except ContainerError as e:
+            logger.error(f"Container error: {e}")
+            return ExecutionResponse(
+                stdout="",
+                stderr=str(e),
+                exit_code=e.exit_status,
+                execution_time=time.time() - start_time,
+                error="Container execution failed"
+            )
+            
+        except APIError as e:
+            logger.error(f"Docker API error: {e}")
+            return ExecutionResponse(
+                stdout="",
+                stderr="",
+                exit_code=-1,
+                execution_time=time.time() - start_time,
+                error=f"Docker API error: {str(e)}"
+            )
+            
+        except Exception as e:
+            logger.error(f"Unexpected error during execution: {e}", exc_info=True)
+            return ExecutionResponse(
+                stdout="",
+                stderr="",
+                exit_code=-1,
+                execution_time=time.time() - start_time,
+                error=f"Unexpected error: {str(e)}"
+            )
+            
+        finally:
+            # Always cleanup container
+            if container:
+                try:
+                    container.remove(force=True)
+                    logger.debug(f"Container {container.id[:12]} removed")
+                except Exception as e:
+                    logger.warning(f"Failed to remove container: {e}")
+    
+    def cleanup_all(self):
+        """Remove all stopped containers (maintenance task)"""
+        try:
+            containers = self.client.containers.list(all=True, filters={"status": "exited"})
+            for container in containers:
+                try:
+                    container.remove()
+                    logger.info(f"Cleaned up container {container.id[:12]}")
+                except Exception as e:
+                    logger.warning(f"Failed to remove container {container.id[:12]}: {e}")
+        except Exception as e:
+            logger.error(f"Failed to cleanup containers: {e}")

sandbox/file_manager.py

@@ -0,0 +1,277 @@
+import docker
+from docker.errors import DockerException, NotFound
+import os
+import logging
+from datetime import datetime
+from typing import Optional, List, BinaryIO
+from pathlib import Path
+import mimetypes
+
+from sandbox.models import FileInfo, FileUploadResponse
+
+logger = logging.getLogger(__name__)
+
+
+class FileManager:
+    """
+    Manages file operations within session containers.
+    
+    Handles:
+    - File uploads to session volumes
+    - File downloads from sessions
+    - Directory listing
+    - File deletion
+    - Path validation and security
+    """
+    
+    # Security settings
+    MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
+    MAX_SESSION_SIZE = 100 * 1024 * 1024  # 100MB
+    
+    ALLOWED_EXTENSIONS = {
+        '.py', '.js', '.ts', '.java', '.go', '.rs',
+        '.sh', '.bash', '.txt', '.md', '.json',
+        '.yaml', '.yml', '.toml', '.xml', '.html',
+        '.css', '.c', '.cpp', '.h', '.hpp'
+    }
+    
+    def __init__(self):
+        try:
+            self.client = docker.from_env()
+            logger.info("File manager initialized")
+        except DockerException as e:
+            logger.error(f"Failed to initialize Docker client: {e}")
+            raise RuntimeError("Docker is not available") from e
+    
+    def _validate_path(self, filepath: str) -> str:
+        """
+        Validate and sanitize file path.
+        
+        Prevents path traversal attacks.
+        """
+        # Remove any path traversal attempts
+        clean_path = os.path.normpath(filepath).lstrip('/')
+        
+        # Ensure it doesn't escape workspace
+        if clean_path.startswith('..') or '/../' in clean_path:
+            raise ValueError("Path traversal detected")
+        
+        return f"/workspace/{clean_path}"
+    
+    def _validate_extension(self, filename: str) -> bool:
+        """Check if file extension is allowed"""
+        ext = os.path.splitext(filename)[1].lower()
+        return ext in self.ALLOWED_EXTENSIONS or ext == ''
+    
+    def upload_file(
+        self,
+        container_id: str,
+        filename: str,
+        file_data: bytes
+    ) -> FileUploadResponse:
+        """
+        Upload file to session container.
+        
+        Args:
+            container_id: Target container ID
+            filename: Name of file to create
+            file_data: File binary data
+            
+        Returns:
+            FileUploadResponse with file details
+        """
+        # Validate file size
+        if len(file_data) > self.MAX_FILE_SIZE:
+            raise ValueError(f"File size exceeds limit of {self.MAX_FILE_SIZE} bytes")
+        
+        # Validate filename
+        if not filename or '/' in filename or '\\\\' in filename:
+            raise ValueError("Invalid filename")
+        
+        # Validate extension
+        if not self._validate_extension(filename):
+            raise ValueError(f"File extension not allowed. Allowed: {', '.join(self.ALLOWED_EXTENSIONS)}")
+        
+        try:
+            container = self.client.containers.get(container_id)
+            
+            # Create file path
+            file_path = f"/workspace/{filename}"
+            
+            # Write file using docker exec
+            # Create temp directory and write file
+            import tarfile
+            import io
+            
+            # Create tar archive in memory
+            tar_stream = io.BytesIO()
+            tar = tarfile.open(fileobj=tar_stream, mode='w')
+            
+            # Create file info
+            tarinfo = tarfile.TarInfo(name=filename)
+            tarinfo.size = len(file_data)
+            tarinfo.mtime = datetime.utcnow().timestamp()
+            
+            # Add file to tar
+            tar.addfile(tarinfo, io.BytesIO(file_data))
+            tar.close()
+            
+            # Upload tar to container
+            tar_stream.seek(0)
+            container.put_archive('/workspace', tar_stream)
+            
+            logger.info(f"Uploaded file {filename} to container {container_id[:12]}")
+            
+            # Detect MIME type
+            mime_type, _ = mimetypes.guess_type(filename)
+            
+            return FileUploadResponse(
+                filename=filename,
+                path=file_path,
+                size=len(file_data),
+                message=f"File '{filename}' uploaded successfully"
+            )
+            
+        except NotFound:
+            raise ValueError(f"Container {container_id} not found")
+        except Exception as e:
+            logger.error(f"Error uploading file: {e}", exc_info=True)
+            raise RuntimeError(f"Failed to upload file: {str(e)}")
+    
+    def download_file(self, container_id: str, filepath: str) -> bytes:
+        """
+        Download file from session container.
+        
+        Args:
+            container_id: Source container ID
+            filepath: Path to file (relative to /workspace)
+            
+        Returns:
+            File binary data
+        """
+        # Validate and sanitize path
+        safe_path = self._validate_path(filepath)
+        
+        try:
+            container = self.client.containers.get(container_id)
+            
+            # Get file as tar stream
+            bits, stat = container.get_archive(safe_path)
+            
+            # Extract file from tar
+            import tarfile
+            import io
+            
+            tar_stream = io.BytesIO()
+            for chunk in bits:
+                tar_stream.write(chunk)
+            tar_stream.seek(0)
+            
+            tar = tarfile.open(fileobj=tar_stream)
+            
+            # Get first member (the file)
+            member = tar.getmembers()[0]
+            file_obj = tar.extractfile(member)
+            file_data = file_obj.read()
+            
+            logger.info(f"Downloaded file {filepath} from container {container_id[:12]}")
+            return file_data
+            
+        except NotFound:
+            raise ValueError(f"File {filepath} not found in container")
+        except Exception as e:
+            logger.error(f"Error downloading file: {e}", exc_info=True)
+            raise RuntimeError(f"Failed to download file: {str(e)}")
+    
+    def list_files(self, container_id: str, directory: str = "/workspace") -> List[FileInfo]:
+        """
+        List files in session directory.
+        
+        Args:
+            container_id: Container ID
+            directory: Directory to list
+            
+        Returns:
+            List of FileInfo objects
+        """
+        # Validate path
+        safe_dir = self._validate_path(directory)
+        
+        try:
+            container = self.client.containers.get(container_id)
+            
+            # Execute ls command
+            result = container.exec_run(
+                f"find {safe_dir} -maxdepth 1 -type f -exec stat -c '%n|%s|%Y' {{}} \\;",
+                demux=True
+            )
+            
+            if result.exit_code != 0:
+                logger.warning(f"Failed to list files: {result.output}")
+                return []
+            
+            stdout = result.output[0].decode('utf-8') if result.output[0] else ""
+            
+            files = []
+            for line in stdout.strip().split('\\n'):
+                if not line:
+                    continue
+                
+                try:
+                    path, size, mtime = line.split('|')
+                    filename = os.path.basename(path)
+                    
+                    # Get MIME type
+                    mime_type, _ = mimetypes.guess_type(filename)
+                    
+                    files.append(FileInfo(
+                        filename=filename,
+                        path=path,
+                        size=int(size),
+                        modified_at=datetime.fromtimestamp(int(mtime)),
+                        mime_type=mime_type or 'application/octet-stream'
+                    ))
+                except Exception as e:
+                    logger.warning(f"Failed to parse file info: {line}, error: {e}")
+                    continue
+            
+            return files
+            
+        except NotFound:
+            raise ValueError(f"Container {container_id} not found")
+        except Exception as e:
+            logger.error(f"Error listing files: {e}", exc_info=True)
+            return []
+    
+    def delete_file(self, container_id: str, filepath: str) -> bool:
+        """
+        Delete file from session.
+        
+        Args:
+            container_id: Container ID
+            filepath: Path to file
+            
+        Returns:
+            True if deleted successfully
+        """
+        # Validate path
+        safe_path = self._validate_path(filepath)
+        
+        try:
+            container = self.client.containers.get(container_id)
+            
+            # Execute rm command
+            result = container.exec_run(f"rm {safe_path}")
+            
+            if result.exit_code == 0:
+                logger.info(f"Deleted file {filepath} from container {container_id[:12]}")
+                return True
+            else:
+                logger.warning(f"Failed to delete file: {result.output}")
+                return False
+                
+        except NotFound:
+            raise ValueError(f"Container {container_id} not found")
+        except Exception as e:
+            logger.error(f"Error deleting file: {e}", exc_info=True)
+            return False

sandbox/images/bash.Dockerfile

@@ -0,0 +1,27 @@
+# Minimal, hardened Bash execution image
+FROM bash:5.2-alpine
+
+# Install security updates and minimal utilities
+RUN apk update && apk upgrade && \
+    apk add --no-cache \
+        coreutils \
+        procps \
+        net-tools \
+        curl \
+        && \
+    rm -rf /var/cache/apk/*
+
+# Create non-root user
+RUN adduser -D -s /bin/bash sandbox
+
+# Set working directory
+WORKDIR /sandbox
+
+# Change ownership to sandbox user
+RUN chown -R sandbox:sandbox /sandbox
+
+# Switch to non-root user
+USER sandbox
+
+# Default command
+CMD ["bash"]

sandbox/images/devenv.Dockerfile

@@ -0,0 +1,108 @@
+# Multi-Language Development Environment
+# Based on Ubuntu 24.04 with Python, Node.js, Java, Go, Rust, Docker
+
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=UTC
+
+# Install base utilities
+RUN apt-get update && apt-get install -y \\
+    curl wget git build-essential ca-certificates gnupg lsb-release \\
+    software-properties-common apt-transport-https \\
+    sudo vim nano tmux \\
+    jq ripgrep fd-find bat \\
+    && rm -rf /var/lib/apt/lists/*
+
+# ========== Python Environment ==========
+RUN apt-get update && apt-get install -y \\
+    python3.12 python3.12-dev python3.12-venv \\
+    python3-pip pipx \\
+    && rm -rf /var/lib/apt/lists/*
+
+# Install pyenv for Python version management
+RUN curl https://pyenv.run | bash
+ENV PATH="/root/.pyenv/bin:${PATH}"
+RUN echo 'eval "$(pyenv init -)"' >> ~/.bashrc
+
+# Install Poetry
+RUN pipx install poetry && pipx ensurepath
+
+# Install Python tools
+RUN pip3 install --no-cache-dir --break-system-packages \\
+    uv black mypy pytest ruff
+
+# ========== Node.js Environment ==========
+# Install nvm
+RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
+ENV NVM_DIR="/root/.nvm"
+RUN . "$NVM_DIR/nvm.sh" && \\
+    nvm install 22 && \\
+    nvm install 20 && \\
+    nvm install 18 && \\
+    nvm alias default 22 && \\
+    nvm use 22
+
+# Install npm global tools
+RUN . "$NVM_DIR/nvm.sh" && \\
+    npm install -g yarn pnpm eslint prettier
+
+# ========== Java Environment ==========
+RUN apt-get update && apt-get install -y \\
+    openjdk-21-jdk maven gradle \\
+    && rm -rf /var/lib/apt/lists/*
+
+# ========== Go Environment ==========
+RUN wget https://go.dev/dl/go1.24.3.linux-amd64.tar.gz && \\
+    tar -C /usr/local -xzf go1.24.3.linux-amd64.tar.gz && \\
+    rm go1.24.3.linux-amd64.tar.gz
+ENV PATH="/usr/local/go/bin:${PATH}"
+ENV GOPATH="/root/go"
+ENV PATH="${GOPATH}/bin:${PATH}"
+
+# ========== Rust Environment ==========
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+# ========== Docker-in-Docker ==========
+RUN curl -fsSL https://get.docker.com -o get-docker.sh && \\
+    sh get-docker.sh && \\
+    rm get-docker.sh
+
+# ========== C/C++ Compilers ==========
+RUN apt-get update && apt-get install -y \\
+    clang gcc g++ cmake ninja-build \\
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Conan
+RUN pip3 install --no-cache-dir --break-system-packages conan
+
+# ========== Other Utilities ==========
+RUN apt-get update && apt-get install -y \\
+    gawk sed grep tar gzip bzip2 xz-utils \\
+    make automake autoconf \\
+    openssh-client \\
+    && rm -rf /var/lib/apt/lists/*
+
+# Install yq
+RUN wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/bin/yq && \\
+    chmod +x /usr/bin/yq
+
+# Create developer user
+RUN useradd -m -u 1000 -G sudo developer && \\
+    echo "developer:developer" | chpasswd && \\
+    echo "developer ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+
+# Create workspace
+RUN mkdir -p /workspace && chown developer:developer /workspace
+
+# Copy environment check script
+COPY environment_check.sh /opt/environment_check.sh
+RUN chmod +x /opt/environment_check.sh
+
+# Set default user
+USER developer
+WORKDIR /workspace
+
+# Default command (keep container running)
+CMD ["tail", "-f", "/dev/null"]

sandbox/images/environment_check.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# Environment validation script
+
+echo "============================="
+echo "Environment Check"
+echo "============================="
+echo ""
+
+# Colors for output
+GREEN='\\033[0;32m'
+RED='\\033[0;31m'
+NC='\\033[0m' # No Color
+
+check_command() {
+    if command -v $1 &> /dev/null; then
+        echo -e "${GREEN}✅${NC} $1: $($@)"
+    else
+        echo -e "${RED}❌${NC} $1: not found"
+    fi
+}
+
+echo "-------- Python --------"
+check_command python3 --version
+check_command python --version
+check_command pip3 --version
+check_command pipx --version
+check_command poetry --version
+check_command uv --version
+check_command black --version
+check_command mypy --version
+check_command pytest --version
+check_command ruff --version
+echo ""
+
+echo "-------- NodeJS --------"
+if [ -s "$NVM_DIR/nvm.sh" ]; then
+    . "$NVM_DIR/nvm.sh"
+    check_command node --version
+    nvm list
+else
+    check_command node --version
+fi
+check_command npm --version
+check_command yarn --version
+check_command pnpm --version
+check_command eslint --version
+check_command prettier --version
+echo ""
+
+echo "-------- Java --------"
+check_command java --version
+check_command mvn --version
+check_command gradle --version
+echo ""
+
+echo "-------- Go --------"
+check_command go version
+echo ""
+
+echo "-------- Rust --------"
+check_command rustc --version
+check_command cargo --version
+echo ""
+
+echo "-------- C/C++ Compilers --------"
+check_command clang --version
+check_command gcc --version
+check_command cmake --version
+check_command ninja --version
+check_command conan --version
+echo ""
+
+echo "-------- Docker --------"
+check_command docker --version
+check_command docker compose version
+echo ""
+
+echo "-------- Other Utilities --------"
+check_command awk --version
+check_command curl --version
+check_command git --version
+check_command grep --version
+check_command gzip --version
+check_command jq --version
+check_command make --version
+check_command rg --version
+check_command sed --version
+check_command tar --version
+check_command tmux -V
+check_command yq --version
+echo ""
+
+echo "============================="
+echo "Environment check complete!"
+echo "============================="

sandbox/images/javascript.Dockerfile

@@ -0,0 +1,26 @@
+# Minimal, hardened Node.js execution image
+FROM node:20-alpine
+
+# Install security updates and minimal dependencies
+RUN apk update && apk upgrade && \
+    apk add --no-cache \
+        bash \
+        curl \
+        && \
+    rm -rf /var/cache/apk/*
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+# Set working directory
+WORKDIR /sandbox
+
+# Change ownership to nodejs user
+RUN chown -R nodejs:nodejs /sandbox
+
+# Switch to non-root user
+USER nodejs
+
+# Default command
+CMD ["node"]

sandbox/images/python.Dockerfile

@@ -0,0 +1,21 @@
+# Minimal, hardened Python execution image
+FROM python:3.11-slim-alpine
+
+# Install security updates and minimal dependencies
+RUN apk update && apk upgrade && \
+    apk add --no-cache \
+        bash \
+        && \
+    rm -rf /var/cache/apk/*
+
+# Create non-root user
+RUN adduser -D -s /bin/bash sandbox
+
+# Set working directory
+WORKDIR /sandbox
+
+# Switch to non-root user
+USER sandbox
+
+# Default command
+CMD ["python3"]

sandbox/language_runners.py

@@ -0,0 +1,54 @@
+from sandbox.models import Language, LanguageInfo
+
+
+class LanguageRunner:
+    """Base configuration for language runners"""
+    
+    @staticmethod
+    def get_runner_config(language: Language) -> dict:
+        """Get Docker configuration for a specific language"""
+        configs = {
+            Language.PYTHON: {
+                "image": "python:3.11-slim",
+                "command": ["python", "-c"],
+                "version": "3.11",
+                "extensions": [".py"],
+            },
+            Language.JAVASCRIPT: {
+                "image": "node:20-alpine",
+                "command": ["node", "-e"],
+                "version": "20",
+                "extensions": [".js"],
+            },
+            Language.BASH: {
+                "image": "bash:5.2-alpine",
+                "command": ["bash", "-c"],
+                "version": "5.2",
+                "extensions": [".sh"],
+            },
+        }
+        return configs.get(language, configs[Language.PYTHON])
+    
+    @staticmethod
+    def get_all_languages() -> list[LanguageInfo]:
+        """Get information about all supported languages"""
+        return [
+            LanguageInfo(
+                name="Python",
+                version="3.11",
+                image="python:3.11-slim",
+                extensions=[".py"]
+            ),
+            LanguageInfo(
+                name="JavaScript",
+                version="20",
+                image="node:20-alpine",
+                extensions=[".js"]
+            ),
+            LanguageInfo(
+                name="Bash",
+                version="5.2",
+                image="bash:5.2-alpine",
+                extensions=[".sh"]
+            ),
+        ]

sandbox/models.py

@@ -0,0 +1,115 @@
+from pydantic import BaseModel, Field, field_validator
+from typing import Optional, Literal, Dict, Any
+from enum import Enum
+from datetime import datetime
+import uuid
+
+
+class Language(str, Enum):
+    """Supported programming languages"""
+    PYTHON = "python"
+    JAVASCRIPT = "javascript"
+    BASH = "bash"
+
+
+class ExecutionRequest(BaseModel):
+    """Request model for code execution"""
+    code: str = Field(..., description="Code to execute", min_length=1, max_length=50000)
+    language: Language = Field(..., description="Programming language")
+    stdin: str = Field(default="", description="Standard input for the code")
+    timeout: int = Field(default=10, ge=1, le=30, description="Execution timeout in seconds")
+    memory_limit: int = Field(default=256, ge=64, le=512, description="Memory limit in MB")
+
+    @field_validator('code')
+    @classmethod
+    def validate_code(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Code cannot be empty or whitespace only")
+        return v
+
+
+class ExecutionResponse(BaseModel):
+    """Response model for code execution"""
+    stdout: str = Field(default="", description="Standard output")
+    stderr: str = Field(default="", description="Standard error")
+    exit_code: int = Field(..., description="Exit code of the process")
+    execution_time: float = Field(..., description="Execution time in seconds")
+    error: Optional[str] = Field(default=None, description="Error message if execution failed")
+
+
+class SandboxConfig(BaseModel):
+    """Configuration for sandbox execution"""
+    max_execution_time: int = Field(default=30, description="Maximum execution time in seconds")
+    max_memory_mb: int = Field(default=512, description="Maximum memory in MB")
+    enable_network: bool = Field(default=False, description="Enable network access in sandbox")
+    read_only_root: bool = Field(default=True, description="Make root filesystem read-only")
+    max_output_size: int = Field(default=1048576, description="Maximum output size in bytes (1MB)")
+
+
+class LanguageInfo(BaseModel):
+    """Information about a supported language"""
+    name: str
+    version: str
+    image: str
+    extensions: list[str]
+
+
+class SessionStatus(str, Enum):
+    """Session lifecycle status"""
+    CREATING = "creating"
+    READY = "ready"
+    BUSY = "busy"
+    STOPPING = "stopping"
+    ERROR = "error"
+
+
+class CreateSessionRequest(BaseModel):
+    """Request to create a new persistent session"""
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="User-defined metadata")
+    timeout_minutes: int = Field(default=30, ge=5, le=120, description="Session idle timeout in minutes")
+
+
+class SessionResponse(BaseModel):
+    """Response with session information"""
+    session_id: str
+    container_id: str
+    volume_name: str
+    status: SessionStatus
+    created_at: datetime
+    last_activity: datetime
+    timeout_minutes: int
+    metadata: Dict[str, Any]
+    files_count: Optional[int] = None
+
+
+class FileInfo(BaseModel):
+    """Information about a file in session"""
+    filename: str
+    path: str
+    size: int
+    modified_at: datetime
+    mime_type: str
+
+
+class FileUploadResponse(BaseModel):
+    """Response after file upload"""
+    filename: str
+    path: str
+    size: int
+    message: str = "File uploaded successfully"
+
+
+class ExecuteInSessionRequest(BaseModel):
+    """Request to execute code in an existing session"""
+    code: str = Field(..., min_length=1, max_length=50000)
+    language: Language
+    working_dir: str = Field(default="/workspace", description="Working directory for execution")
+    timeout: int = Field(default=30, ge=1, le=120)
+
+
+class ExecuteFileRequest(BaseModel):
+    """Request to execute an uploaded file"""
+    filepath: str = Field(..., description="Path to file in session workspace")
+    language: Language
+    args: list[str] = Field(default_factory=list, description="Command-line arguments")
+    timeout: int = Field(default=30, ge=1, le=120)

sandbox/session_manager.py

@@ -0,0 +1,246 @@
+import docker
+from docker.errors import DockerException, NotFound, APIError
+import logging
+import uuid
+from datetime import datetime, timedelta
+from typing import Dict, Optional, List
+import threading
+import time
+
+from sandbox.models import (
+    SessionResponse, SessionStatus, CreateSessionRequest,
+    SandboxConfig
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SessionManager:
+    """
+    Manages persistent VM-like container sessions.
+    
+    Each session is a long-running Docker container with:
+    - Persistent volume for file storage
+    - Multi-language development environment
+    - Dedicated workspace directory
+    """
+    
+    def __init__(self, config: Optional[SandboxConfig] = None):
+        self.config = config or SandboxConfig()
+        try:
+            self.client = docker.from_env()
+            self.client.ping()
+            logger.info("Docker client initialized for session management")
+        except DockerException as e:
+            logger.error(f"Failed to initialize Docker client: {e}")
+            raise RuntimeError("Docker is not available") from e
+        
+        # In-memory session registry (use Redis for production)
+        self.sessions: Dict[str, SessionResponse] = {}
+        self._lock = threading.Lock()
+        
+        # Start cleanup thread
+        self._cleanup_thread = threading.Thread(target=self._cleanup_loop, daemon=True)
+        self._cleanup_thread.start()
+        logger.info("Session cleanup thread started")
+    
+    def create_session(self, request: CreateSessionRequest) -> SessionResponse:
+        """
+        Create a new persistent session.
+        
+        Args:
+            request: Session creation request
+            
+        Returns:
+            SessionResponse with session details
+        """
+        session_id = str(uuid.uuid4())
+        volume_name = f"sandbox-session-{session_id}"
+        
+        try:
+            # Create dedicated volume
+            logger.info(f"Creating volume {volume_name}")
+            volume = self.client.volumes.create(
+                name=volume_name,
+                driver='local',
+                labels={'session_id': session_id}
+            )
+            
+            # Create long-running container
+            logger.info(f"Creating session container for {session_id}")
+            container = self.client.containers.create(
+                image='sandbox-devenv:latest',  # Our multi-language image
+                name=f"sandbox-session-{session_id}",
+                detach=True,
+                
+                # Mount volume to workspace
+                volumes={
+                    volume_name: {'bind': '/workspace', 'mode': 'rw'}
+                },
+                
+                # Keep container running
+                command='tail -f /dev/null',
+                
+                # Resource limits
+                mem_limit=f"{self.config.max_memory_mb}m",
+                memswap_limit=f"{self.config.max_memory_mb}m",
+                cpu_quota=100000,  # 1 CPU core
+                cpu_period=100000,
+                
+                # Network isolation (can be disabled for package installation)
+                network_mode="bridge" if self.config.enable_network else "none",
+                
+                # Security
+                read_only=False,  # Need write access for development
+                security_opt=["no-new-privileges"],
+                
+                # Working directory
+                working_dir='/workspace',
+                
+                # Labels for tracking
+                labels={
+                    'session_id': session_id,
+                    'managed_by': 'sandbox-api'
+                }
+            )
+            
+            # Start the container
+            container.start()
+            logger.info(f"Started container {container.id[:12]} for session {session_id}")
+            
+            # Create session object
+            now = datetime.utcnow()
+            session = SessionResponse(
+                session_id=session_id,
+                container_id=container.id,
+                volume_name=volume_name,
+                status=SessionStatus.READY,
+                created_at=now,
+                last_activity=now,
+                timeout_minutes=request.timeout_minutes,
+                metadata=request.metadata,
+                files_count=0
+            )
+            
+            # Store in registry
+            with self._lock:
+                self.sessions[session_id] = session
+            
+            logger.info(f"Session {session_id} created successfully")
+            return session
+            
+        except Exception as e:
+            logger.error(f"Failed to create session: {e}", exc_info=True)
+            # Cleanup on failure
+            try:
+                if volume_name:
+                    vol = self.client.volumes.get(volume_name)
+                    vol.remove(force=True)
+            except:
+                pass
+            raise RuntimeError(f"Failed to create session: {str(e)}")
+    
+    def get_session(self, session_id: str) -> Optional[SessionResponse]:
+        """Get session by ID"""
+        with self._lock:
+            session = self.sessions.get(session_id)
+            if session:
+                # Update status from container
+                try:
+                    container = self.client.containers.get(session.container_id)
+                    if container.status == 'running':
+                        session.status = SessionStatus.READY
+                    else:
+                        session.status = SessionStatus.ERROR
+                except:
+                    session.status = SessionStatus.ERROR
+            return session
+    
+    def list_sessions(self) -> List[SessionResponse]:
+        """List all active sessions"""
+        with self._lock:
+            return list(self.sessions.values())
+    
+    def update_activity(self, session_id: str):
+        """Update last activity timestamp for a session"""
+        with self._lock:
+            if session_id in self.sessions:
+                self.sessions[session_id].last_activity = datetime.utcnow()
+    
+    def destroy_session(self, session_id: str) -> bool:
+        """
+        Destroy a session and cleanup resources.
+        
+        Args:
+            session_id: Session to destroy
+            
+        Returns:
+            True if destroyed, False if not found
+        """
+        with self._lock:
+            session = self.sessions.pop(session_id, None)
+        
+        if not session:
+            logger.warning(f"Session {session_id} not found")
+            return False
+        
+        try:
+            # Stop and remove container
+            try:
+                container = self.client.containers.get(session.container_id)
+                container.stop(timeout=5)
+                container.remove(force=True)
+                logger.info(f"Removed container {session.container_id[:12]}")
+            except NotFound:
+                logger.warning(f"Container {session.container_id[:12]} not found")
+            except Exception as e:
+                logger.error(f"Error removing container: {e}")
+            
+            # Remove volume
+            try:
+                volume = self.client.volumes.get(session.volume_name)
+                volume.remove(force=True)
+                logger.info(f"Removed volume {session.volume_name}")
+            except NotFound:
+                logger.warning(f"Volume {session.volume_name} not found")
+            except Exception as e:
+                logger.error(f"Error removing volume: {e}")
+            
+            logger.info(f"Session {session_id} destroyed successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error destroying session {session_id}: {e}", exc_info=True)
+            return False
+    
+    def _cleanup_loop(self):
+        """Background thread to cleanup idle sessions"""
+        while True:
+            try:
+                time.sleep(60)  # Check every minute
+                self._cleanup_idle_sessions()
+            except Exception as e:
+                logger.error(f"Error in cleanup loop: {e}", exc_info=True)
+    
+    def _cleanup_idle_sessions(self):
+        """Cleanup sessions that have exceeded their timeout"""
+        now = datetime.utcnow()
+        sessions_to_destroy = []
+        
+        with self._lock:
+            for session_id, session in self.sessions.items():
+                timeout = timedelta(minutes=session.timeout_minutes)
+                if (now - session.last_activity) > timeout:
+                    sessions_to_destroy.append(session_id)
+                    logger.info(f"Session {session_id} exceeded timeout, will cleanup")
+        
+        # Destroy outside lock to avoid deadlock
+        for session_id in sessions_to_destroy:
+            self.destroy_session(session_id)
+    
+    def shutdown(self):
+        """Cleanup all sessions on shutdown"""
+        logger.info("Shutting down session manager, cleaning up all sessions")
+        session_ids = list(self.sessions.keys())
+        for session_id in session_ids:
+            self.destroy_session(session_id)

tests/__init__.py

@@ -0,0 +1 @@
+# Test package

tests/test_api.py

@@ -0,0 +1,166 @@
+import pytest
+from fastapi.testclient import TestClient
+from app import app
+
+
+@pytest.fixture
+def client():
+    """FastAPI test client fixture"""
+    return TestClient(app)
+
+
+def test_root_endpoint(client):
+    """Test root endpoint returns API info"""
+    response = client.get("/")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["name"] == "Code Execution Sandbox API"
+    assert data["version"] == "1.0.0"
+    assert "supported_languages" in data
+
+
+def test_health_endpoint(client):
+    """Test health check endpoint"""
+    response = client.get("/health")
+    # May fail if Docker is not available, but endpoint should exist
+    assert response.status_code in [200, 503]
+
+
+def test_languages_endpoint(client):
+    """Test languages listing endpoint"""
+    response = client.get("/languages")
+    assert response.status_code == 200
+    data = response.json()
+    assert "languages" in data
+    languages = data["languages"]
+    assert len(languages) == 3
+    
+    # Check language names
+    lang_names = [lang["name"] for lang in languages]
+    assert "Python" in lang_names
+    assert "JavaScript" in lang_names
+    assert "Bash" in lang_names
+
+
+def test_execute_python_hello_world(client):
+    """Test executing simple Python code"""
+    response = client.post("/execute", json={
+        "code": "print('Hello, World!')",
+        "language": "python"
+    })
+    
+    # If Docker is not available, this may fail with 503
+    if response.status_code == 200:
+        data = response.json()
+        assert "Hello, World!" in data["stdout"]
+        assert data["exit_code"] == 0
+        assert data["error"] is None
+
+
+def test_execute_python_math(client):
+    """Test Python arithmetic"""
+    response = client.post("/execute", json={
+        "code": "result = 2 + 2\nprint(f'Result: {result}')",
+        "language": "python"
+    })
+    
+    if response.status_code == 200:
+        data = response.json()
+        assert "Result: 4" in data["stdout"]
+        assert data["exit_code"] == 0
+
+
+def test_execute_javascript_hello_world(client):
+    """Test executing simple JavaScript code"""
+    response = client.post("/execute", json={
+        "code": "console.log('Hello from Node.js!');",
+        "language": "javascript"
+    })
+    
+    if response.status_code == 200:
+        data = response.json()
+        assert "Hello from Node.js!" in data["stdout"]
+        assert data["exit_code"] == 0
+
+
+def test_execute_bash_command(client):
+    """Test executing Bash command"""
+    response = client.post("/execute", json={
+        "code": "echo 'Bash works!'",
+        "language": "bash"
+    })
+    
+    if response.status_code == 200:
+        data = response.json()
+        assert "Bash works!" in data["stdout"]
+        assert data["exit_code"] == 0
+
+
+def test_execute_with_syntax_error(client):
+    """Test executing code with syntax error"""
+    response = client.post("/execute", json={
+        "code": "print('missing closing quote)",
+        "language": "python"
+    })
+    
+    if response.status_code == 200:
+        data = response.json()
+        assert data["exit_code"] != 0
+        # Should have error in stderr or error field
+
+
+def test_execute_with_timeout(client):
+    """Test timeout enforcement"""
+    response = client.post("/execute", json={
+        "code": "import time\ntime.sleep(5)",
+        "language": "python",
+        "timeout": 2
+    })
+    
+    if response.status_code == 200:
+        data = response.json()
+        # Should timeout
+        assert data["execution_time"] < 3
+        assert data["error"] is not None or data["exit_code"] == 124
+
+
+def test_invalid_language(client):
+    """Test invalid language rejection"""
+    response = client.post("/execute", json={
+        "code": "print('test')",
+        "language": "rust"  # Not supported
+    })
+    
+    assert response.status_code == 422  # Validation error
+
+
+def test_empty_code(client):
+    """Test empty code rejection"""
+    response = client.post("/execute", json={
+        "code": "",
+        "language": "python"
+    })
+    
+    assert response.status_code == 422  # Validation error
+
+
+def test_timeout_out_of_range(client):
+    """Test timeout validation"""
+    response = client.post("/execute", json={
+        "code": "print('test')",
+        "language": "python",
+        "timeout": 100  # Exceeds max of 30
+    })
+    
+    assert response.status_code == 422  # Validation error
+
+
+def test_memory_limit_validation(client):
+    """Test memory limit validation"""
+    response = client.post("/execute", json={
+        "code": "print('test')",
+        "language": "python",
+        "memory_limit": 1024  # Exceeds max of 512
+    })
+    
+    assert response.status_code == 422  # Validation error

tests/test_executor.py

@@ -0,0 +1,183 @@
+import pytest
+from sandbox.executor import SandboxExecutor
+from sandbox.models import ExecutionRequest, SandboxConfig, Language
+
+
+# Skip all tests if Docker is not available
+docker = pytest.importorskip("docker")
+
+
+@pytest.fixture
+def executor():
+    """Sandbox executor fixture"""
+    try:
+        return SandboxExecutor(SandboxConfig())
+    except RuntimeError:
+        pytest.skip("Docker is not available")
+
+
+def test_executor_initialization(executor):
+    """Test executor can be initialized"""
+    assert executor is not None
+    assert executor.client is not None
+
+
+def test_execute_python_simple(executor):
+    """Test simple Python execution"""
+    request = ExecutionRequest(
+        code="print('Test')",
+        language=Language.PYTHON
+    )
+    
+    response = executor.execute(request)
+    
+    assert "Test" in response.stdout
+    assert response.exit_code == 0
+    assert response.error is None
+    assert response.execution_time > 0
+
+
+def test_execute_python_with_variables(executor):
+    """Test Python with variable assignment"""
+    request = ExecutionRequest(
+        code="x = 10\ny = 20\nprint(x + y)",
+        language=Language.PYTHON
+    )
+    
+    response = executor.execute(request)
+    
+    assert "30" in response.stdout
+    assert response.exit_code == 0
+
+
+def test_execute_javascript_simple(executor):
+    """Test simple JavaScript execution"""
+    request = ExecutionRequest(
+        code="console.log('JavaScript works!');",
+        language=Language.JAVASCRIPT
+    )
+    
+    response = executor.execute(request)
+    
+    assert "JavaScript works!" in response.stdout
+    assert response.exit_code == 0
+
+
+def test_execute_bash_simple(executor):
+    """Test simple Bash execution"""
+    request = ExecutionRequest(
+        code="echo 'Bash test'",
+        language=Language.BASH
+    )
+    
+    response = executor.execute(request)
+    
+    assert "Bash test" in response.stdout
+    assert response.exit_code == 0
+
+
+def test_timeout_enforcement(executor):
+    """Test that timeout is enforced"""
+    request = ExecutionRequest(
+        code="import time\nwhile True:\n    time.sleep(1)",
+        language=Language.PYTHON,
+        timeout=2
+    )
+    
+    response = executor.execute(request)
+    
+    # Should timeout
+    assert response.execution_time < 3
+    assert response.exit_code == 124 or response.error is not None
+
+
+def test_syntax_error_handling(executor):
+    """Test handling of code with syntax errors"""
+    request = ExecutionRequest(
+        code="print('missing quote)",
+        language=Language.PYTHON
+    )
+    
+    response = executor.execute(request)
+    
+    assert response.exit_code != 0
+    # Error should be captured in stderr or stdout
+    assert len(response.stdout + response.stderr) > 0
+
+
+def test_runtime_error_handling(executor):
+    """Test handling of runtime errors"""
+    request = ExecutionRequest(
+        code="x = 1 / 0",  # Division by zero
+        language=Language.PYTHON
+    )
+    
+    response = executor.execute(request)
+    
+    assert response.exit_code != 0
+
+
+def test_container_cleanup(executor):
+    """Test that containers are cleaned up after execution"""
+    import docker
+    client = docker.from_env()
+    
+    # Get initial container count
+    initial_containers = len(client.containers.list(all=True))
+    
+    # Execute code
+    request = ExecutionRequest(
+        code="print('cleanup test')",
+        language=Language.PYTHON
+    )
+    executor.execute(request)
+    
+    # Check container count after execution
+    final_containers = len(client.containers.list(all=True))
+    
+    # Should be the same (container was cleaned up)
+    assert final_containers == initial_containers
+
+
+def test_memory_limit_config(executor):
+    """Test that memory limit is applied"""
+    request = ExecutionRequest(
+        code="print('memory test')",
+        language=Language.PYTHON,
+        memory_limit=128
+    )
+    
+    response = executor.execute(request)
+    
+    # Should execute successfully with lower memory
+    assert response.exit_code == 0
+
+
+def test_output_truncation(executor):
+    """Test that large output is truncated"""
+    # Generate large output
+    code = "for i in range(100000):\n    print('x' * 100)"
+    
+    request = ExecutionRequest(
+        code=code,
+        language=Language.PYTHON
+    )
+    
+    response = executor.execute(request)
+    
+    # Output should be truncated
+    assert "truncated" in response.stdout or len(response.stdout) <= executor.config.max_output_size + 100
+
+
+def test_multiple_executions(executor):
+    """Test multiple consecutive executions"""
+    for i in range(5):
+        request = ExecutionRequest(
+            code=f"print('Execution {i}')",
+            language=Language.PYTHON
+        )
+        
+        response = executor.execute(request)
+        
+        assert f"Execution {i}" in response.stdout
+        assert response.exit_code == 0