---
title: Code Execution Sandbox API
emoji: 🔒
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
---

# Code Execution Sandbox API - Enhanced

Secure, isolated code execution environment with **persistent VM-like sessions** and **file system operations**.

## 🚀 Features

### Dual Execution Modes

1. **Stateless Execution** - Quick, ephemeral code execution (backward compatible)
2. **Persistent Sessions** - Long-running containers with file storage and state persistence

### Capabilities

- ✅ **Multi-Language Support**: Python, JavaScript, Bash (+ Go, Java, Rust in sessions)
- ✅ **Secure Isolation**: Docker-based containerization with resource limits
- ✅ **File Operations**: Upload, download, list, execute files
- ✅ **Persistent State**: Files and data persist across executions within a session
- ✅ **Auto-Cleanup**: Idle sessions automatically destroyed after timeout
- ✅ **Resource Limits**: CPU, memory, timeout enforcement
- ✅ **Network Isolation**: Disabled by default (configurable)

## 📦 Installation

### Prerequisites

- Python 3.8+
- Docker (must be running)
- 4GB+ RAM recommended

### Setup

```bash
# Clone repository
git clone <repo-url>
cd isolated-sandbox

# Create virtual environment
python -m venv .venv
.venv\\Scripts\\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt  # For testing

# Build development environment image (takes 10-15 minutes)
pwsh build_devenv.ps1
# OR manually:
# docker build -f sandbox/images/devenv.Dockerfile -t sandbox-devenv:latest sandbox/images/
```

### Environment Configuration

Copy `.env.example` to `.env` and customize:

```env
MAX_EXECUTION_TIME=30
MAX_MEMORY_MB=512
ENABLE_NETWORK=false
LOG_LEVEL=INFO
```

## 🏃 Quick Start

### Start the API Server

```bash
python app.py
# Or with uvicorn:
# uvicorn app:app --host 0.0.0.0 --port 7860
```

API will be available at `http://localhost:7860`

### API Documentation

Interactive docs: `http://localhost:7860/docs`

## 📚 Usage Examples

### 1. Stateless Execution (Quick & Simple)

```python
import requests

# Execute Python code
response = requests.post("http://localhost:7860/execute", json={
    "code": "print('Hello, World!')",
    "language": "python",
    "timeout": 10
})

print(response.json())
# {
#   "stdout": "Hello, World!\\n",
#   "stderr": "",
#   "exit_code": 0,
#   "execution_time": 0.123
# }
```

### 2. Persistent Session Workflow

```python
import requests
import time

# Step 1: Create a session
session_resp = requests.post("http://localhost:7860/sessions", json={
    "metadata": {"user": "john", "project": "demo"},
    "timeout_minutes": 30
})
session_id = session_resp.json()["session_id"]
print(f"Session created: {session_id}")

# Wait for session to be ready
time.sleep(2)

# Step 2: Upload a file
with open("script.py", "rb") as f:
    files_resp = requests.post(
        f"http://localhost:7860/sessions/{session_id}/files",
        files={"file": ("script.py", f)}
    )
print(f"Uploaded: {files_resp.json()}")

# Step 3: Execute code in session
exec_resp = requests.post(
    f"http://localhost:7860/sessions/{session_id}/execute",
    json={
        "code": "with open('/workspace/data.txt', 'w') as f: f.write('persistent')",
        "language": "python"
    }
)
print(f"Execution: {exec_resp.json()}")

# Step 4: Execute uploaded file
file_exec_resp = requests.post(
    f"http://localhost:7860/sessions/{session_id}/execute-file",
    json={
        "filepath": "/workspace/script.py",
        "language": "python",
        "args": ["--verbose"]
    }
)
print(f"File execution: {file_exec_resp.json()}")

# Step 5: List files
files = requests.get(f"http://localhost:7860/sessions/{session_id}/files")
print(f"Files: {files.json()}")

# Step 6: Download file
download = requests.get(f"http://localhost:7860/sessions/{session_id}/files/data.txt")
print(f"Downloaded content: {download.content}")

# Step 7: Destroy session (cleanup)
requests.delete(f"http://localhost:7860/sessions/{session_id}")
```

### 3. Test State Persistence

```python
# First execution: create file
exec1 = requests.post(f"http://localhost:7860/sessions/{session_id}/execute", json={
    "code": "import json; data = {'count': 1}; json.dump(data, open('/workspace/state.json', 'w'))",
    "language": "python"
})

# Second execution: read and modify (file persists!)
exec2 = requests.post(f"http://localhost:7860/sessions/{session_id}/execute", json={
    "code": """
import json
data = json.load(open('/workspace/state.json'))
data['count'] += 1
print(f'Count: {data["count"]}')
""",
    "language": "python"
})

print(exec2.json()["stdout"])  # Output: Count: 2
```

## 🔌 API Endpoints

### Session Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/sessions` | Create new session |
| GET | `/sessions` | List all sessions |
| GET | `/sessions/{id}` | Get session details |
| DELETE | `/sessions/{id}` | Destroy session |

### File Operations

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/sessions/{id}/files` | Upload file (multipart) |
| GET | `/sessions/{id}/files` | List files in workspace |
| GET | `/sessions/{id}/files/{path}` | Download file |

### Code Execution

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/execute` | Stateless execution (ephemeral) |
| POST | `/sessions/{id}/execute` | Execute code in session |
| POST | `/sessions/{id}/execute-file` | Execute uploaded file |

### Information

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | API information |
| GET | `/health` | Health check |
| GET | `/languages` | List supported languages |

## 🔒 Security Features

### Container Isolation
- Read-only root filesystem
- Non-root user execution
- Network isolation (default: disabled)
- PID limits (prevent fork bombs)
- No new privileges flag

### Resource Limits
- CPU: 1 core (configurable)
- Memory: 512MB default (configurable)
- Execution timeout: 30s default
- Container auto-cleanup

### File Security
- File size limit: 10MB per file
- Session limit: 100MB total
- Allowed extensions only
- Path traversal prevention
- Sandboxed to `/workspace` directory

### Session Management
- Auto-timeout after idle period (30 min default)
- Background cleanup thread
- Volume isolation per session

## 🛠️ Development Environment (Sessions)

The `sandbox-devenv:latest` image includes:

### Languages & Runtimes
- **Python**: 3.12 (pyenv, poetry, uv, pip, black, mypy, pytest, ruff)
- **Node.js**: 22, 20, 18 (nvm, npm, yarn, pnpm, eslint, prettier)
- **Java**: OpenJDK 21 (Maven, Gradle)
- **Go**: 1.24
- **Rust**: 1.87 (rustc, cargo)
- **C/C++**: gcc, clang, cmake, ninja, conan

### Tools & Utilities
- **Version Control**: git
- **Editors**: vim, nano
- **Utilities**: curl, wget, jq, yq, ripgrep, tmux
- **Docker**: Docker-in-Docker support

### Workspace
- Default directory: `/workspace`
- Persistent across executions
- Mounted via Docker volume

## 🧪 Testing

```bash
# Run all tests
pytest

# Run specific test suites
pytest tests/test_api.py          # API integration tests
pytest tests/test_executor.py     # Executor unit tests
pytest tests/test_session_manager.py  # Session management tests
pytest tests/test_file_operations.py  # File operation tests

# Run with coverage
pytest --cov=sandbox --cov-report=html
```

## 🚢 Deployment

### Docker Deployment

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

# Build devenv image (or pull from registry)
RUN docker build -f sandbox/images/devenv.Dockerfile -t sandbox-devenv:latest sandbox/images/

EXPOSE 7860
CMD ["python", "app.py"]
```

### Requirements
- Docker-in-Docker capable host
- 4GB+ RAM (for concurrent sessions)
- Persistent volume for session data (optional)

### Recommended Platforms
- Self-hosted VPS with Docker
- AWS ECS, GCP Cloud Run, Azure Container Instances
- Railway, Render (with Docker support)

### Not Recommended
- ❌ Hugging Face Spaces (no Docker-in-Docker)
- ❌ Vercel, Netlify (serverless, stateless)

## 📊 Configuration

### Session Limits

Edit `sandbox/session_manager.py`:
```python
MAX_CONCURRENT_SESSIONS = 10  # Limit concurrent sessions
SESSION_TIMEOUT_MINUTES = 30  # Auto-cleanup timeout
```

### File Limits

Edit `sandbox/file_manager.py`:
```python
MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB per file
MAX_SESSION_SIZE = 100 * 1024 * 1024  # 100MB per session
```

### Resource Limits

Edit `.env`:
```env
MAX_EXECUTION_TIME=30
MAX_MEMORY_MB=512
ENABLE_NETWORK=false
```

## 🔄 Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    FastAPI Application                   │
├─────────────────────────────────────────────────────────┤
│  Executor     │  Session Manager  │   File Manager       │
│  (stateless)  │  (persistent)     │   (file ops)         │
└───────┬───────┴─────────┬─────────┴──────────┬──────────┘
        │                 │                    │
        ▼                 ▼                    ▼
   ┌─────────┐      ┌──────────────┐    ┌──────────┐
   │Ephemeral│      │Long-Running  │    │ Docker   │
   │Container│      │Container     │    │ Volumes  │
   └─────────┘      └──────────────┘    └──────────┘
        │                 │                    │
        └─────────────────┴────────────────────┘
                          │
                    Docker Engine
```

## 📝 License

MIT License - See LICENSE file for details

## 🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit pull request

## 📮 Support

For issues, questions, or contributions, please open an issue on GitHub.