README.md

---
title: Advanced Code Interpreter Sandbox
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: "24.1.2"
app_file: app.py
pinned: false
license: mit
hardware: t4-small
---

# 🚀 Advanced Code Interpreter Sandbox

A powerful, feature-rich code execution environment on HuggingFace Spaces that rivals e2b.dev! This sandbox provides a comprehensive Python development environment with advanced capabilities.

## ✨ Features

### 🔐 Secure Code Execution
- Safe, sandboxed Python code execution
- Timeout protection (10s default)
- Memory limit controls
- Syntax error handling
- Exception capture and display

### 📁 File System Support
- Upload files directly to the workspace
- Download results and outputs
- Multi-file management
- Real-time file operations (read, delete, list)
- Temporary file storage with session isolation

### 📦 Package Management
- On-the-fly package installation via pip
- Support for popular data science libraries
- Package version management
- Quick install of common packages (numpy, pandas, matplotlib, plotly, etc.)
- Pre-installed essential packages

### 📊 Data Visualization
- Built-in support for:
  - **Matplotlib** - Static plots and charts
  - **Plotly** - Interactive visualizations
  - **Seaborn** - Statistical data visualization
  - **Bokeh** - Interactive plots
  - **Altair** - Declarative visualization
  - **Pillow** - Image processing

### 💾 Session Persistence
- Maintains state throughout session
- File persistence
- Package installation history
- Session information tracking
- Uptime monitoring

### 🔄 Real-time Output
- Streamed stdout/stderr capture
- Live code execution feedback
- Error highlighting
- Output mode selection (stdout, stderr, or both)

### 📝 Multi-file Support
- Create and manage multiple files
- File editor interface
- Switch between files easily
- Automatic file detection
- File metadata tracking

### 🎨 Superior UX
- Clean, modern Gradio interface
- Dark theme support
- Intuitive tabbed interface
- Responsive design
- Syntax highlighting in code editor
- Progress indicators

## 🚀 Getting Started

### 1. Run Your Code
```python
# Write Python code in the editor
print("Hello, World!")

# Import any installed package
import numpy as np
arr = np.array([1, 2, 3, 4, 5])
print(f"Array: {arr}")
print(f"Mean: {np.mean(arr)}")
```

### 2. Install Packages
- Go to "Package Manager" tab
- Enter package names (comma-separated)
- Click "Install"
- Example: `numpy, pandas, matplotlib, plotly`

### 3. Upload Files
- Go to "File Manager" tab
- Upload files using the file picker
- Files are stored in your workspace
- Access files directly in your code

### 4. Data Visualization Example
```python
import matplotlib.pyplot as plt
import numpy as np

# Generate data
x = np.linspace(0, 10, 100)
y = np.sin(x)

# Create plot
plt.figure(figsize=(10, 6))
plt.plot(x, y, 'b-', label='sin(x)')
plt.xlabel('x')
plt.ylabel('y')
plt.title('Sine Wave')
plt.legend()
plt.grid(True)
plt.show()
```

## 📚 Pre-installed Libraries

The following packages are pre-installed and ready to use:
- NumPy
- Pandas
- Matplotlib
- Plotly
- Seaborn
- SciPy
- Scikit-learn
- Pillow
- Requests
- BeautifulSoup4
- NetworkX
- SymPy

## 🔧 Available Packages

You can install additional packages using the Package Manager. Popular options:
- `tensorflow` - Machine learning
- `torch` - Deep learning
- `transformers` - Hugging Face transformers
- `streamlit` - Web app framework
- `dash` - Interactive dashboards
- `openai` - OpenAI API client
- `langchain` - LLM application framework
- `wordcloud` - Text visualization
- `geopandas` - Geospatial analysis
- ` sqlalchemy` - Database ORM

## 🎯 Use Cases

### Data Analysis
```python
import pandas as pd
import matplotlib.pyplot as plt

# Load and analyze data
df = pd.read_csv('your_data.csv')
print(df.head())
df.describe().plot()
plt.show()
```

### Machine Learning
```python
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split

# Train a model
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
model = RandomForestClassifier()
model.fit(X_train, y_train)
```

### Web Scraping
```python
import requests
from bs4 import BeautifulSoup

# Scrape a webpage
url = "https://example.com"
response = requests.get(url)
soup = BeautifulSoup(response.content, 'html.parser')
print(soup.title)
```

### API Integration
```python
import requests
import json

# Call an API
response = requests.get('https://api.github.com/users/octocat')
data = response.json()
print(json.dumps(data, indent=2))
```

## ⚠️ Security Notes

- Code runs in a secure sandbox environment
- No network access to external resources (except for package installation and explicit API calls)
- Files are isolated per session
- Execution timeouts prevent infinite loops
- Maximum memory usage is limited

## 🆚 Compared to e2b.dev

| Feature | Code Interpreter Sandbox | e2b.dev |
|---------|-------------------------|---------|
| Package Installation | ✅ Yes | ✅ Yes |
| File Upload/Download | ✅ Yes | ✅ Yes |
| Data Visualization | ✅ Yes | ✅ Yes |
| Session Persistence | ✅ Yes | ✅ Yes |
| Real-time Output | ✅ Yes | ✅ Yes |
| Multi-file Support | ✅ Yes | ✅ Yes |
| Cost | 🆓 Free on Spaces | 💰 Paid |
| Custom Environment | 🐳 Docker-based | 🐳 Docker-based |
| Pre-installed Libraries | 📦 20+ packages | 📦 Limited |
| GitHub Integration | 🟡 Manual | ✅ Automatic |

## 🎨 Interface Overview

### Code Executor Tab
- Write and execute Python code
- Choose output mode (stdout, stderr, or both)
- Real-time execution feedback
- Syntax highlighting

### File Manager Tab
- Upload files to workspace
- View and manage all files
- Read file contents
- Delete unwanted files

### Package Manager Tab
- Install packages on-the-fly
- View installed packages
- Batch installation support

### Session Info Tab
- View session details
- Monitor uptime
- Track installed packages
- Workspace information

## 🚀 Deployment

This application is designed for HuggingFace Spaces and includes:
- Optimized `requirements.txt`
- Pre-configured dependencies
- Docker support
- GPU acceleration ready

## 📝 Tips & Tricks

1. **Use variables across executions**: Variables persist within a session
2. **Install packages first**: Install required packages before using them
3. **Save important outputs**: Use file operations to save results
4. **Check session info**: Monitor your session status
5. **Explore the interface**: Each tab provides different functionality

## 🤝 Contributing

Contributions are welcome! Areas for improvement:
- Additional language support
- Enhanced visualization options
- More pre-installed packages
- Improved error handling
- Better performance optimization

## 📄 License

This project is open source and available under the MIT License.

## 🙏 Acknowledgments

- Built with [Gradio](https://gradio.app/)
- Powered by [HuggingFace Spaces](https://huggingface.co/spaces)
- Inspired by [e2b.dev](https://e2b.dev/)

---

**Ready to code?** Just start typing in the Code Executor tab! 🚀