BioCage

⚠️ DEVELOPMENT STATUS: This library is currently under active development and is not ready for use. Stay tuned for updates!

BioCage is a fast, secure, and practical Python sandbox designed specifically for safely executing code generated by Large Language Models (LLMs). It provides a robust containerized environment that isolates code execution while maintaining state persistence and file system integration.

🎯 Why BioCage?

BioCage addresses critical needs:

• 🔒 Security: Complete isolation through Docker with no network access and restricted file system
• 🧠 State Persistence: Variables, imports, and functions persist across multiple executions
• 📁 File Integration: Seamlessly expose files and directories to the sandbox
• ⚡ Performance: Fast startup times with optimized container management
• 🛡️ Reliability: Comprehensive error handling with detailed diagnostics
• 🔧 Flexibility: Support for both ephemeral and persistent execution modes

✨ Key Features

🔒 Security First

• Complete Docker containerization with no host system access
• Network isolation (disabled by default)
• Resource limits (memory, CPU, execution time)
• Read-only filesystem with controlled write access
• Safe execution of potentially malicious AI-generated code

🧠 Intelligent State Management

• Variable persistence across executions
• Import persistence - no need to re-import libraries
• Function and class definitions remain available
• DataFrame modifications persist between runs
• Session-based workflows for complex data processing

📁 Advanced File System Integration

• File exposure: Mount individual files from host to container
• Directory exposure: Mount directories with read-only or read-write access
• Temporary file creation: Create files accessible within the sandbox
• Automatic cleanup: Files and mounts cleaned up after execution

⚡ Performance Optimized

• Pre-built images with common data science libraries
• Fast container startup and execution
• Efficient resource usage with proper limits
• Minimal overhead for code execution

🚀 Quick Start

Installation

bash pip install biocage

Basic Usage

```python from biocage import BioCageManager

Simple one-time execution

with BioCageManager() as sandbox: result = sandbox.run('print("Hello from BioCage!")') print(result.stdout) # "Hello from BioCage!" ```

State Persistence Example

```python

Variables and imports persist across executions

sandbox = BioCageManager() sandbox.start_container()

try: # Set up your environment once sandbox.run(""" import pandas as pd import numpy as np

# Define helper functions
def analyze_data(data):
    return {
        'mean': np.mean(data),
        'std': np.std(data),
        'count': len(data)
    }

# Initialize data
df = pd.DataFrame({
    'values': np.random.randn(1000),
    'category': np.random.choice(['A', 'B', 'C'], 1000)
})
""")

# Use the environment in subsequent executions
result = sandbox.run("""
# Everything from previous execution is still available
stats = analyze_data(df['values'])
print(f"Data statistics: {stats}")

# Modify the DataFrame
df['squared'] = df['values'] ** 2
print(f"DataFrame shape: {df.shape}")
""")

print(result.stdout)

finally: sandbox.stop_container() ```

File and Directory Integration

```python

Expose files and directories to the sandbox

with BioCageManager().configurecontextmanager( exposefiles={ "/path/to/data.csv": "/app/data/input.csv", "/path/to/config.json": "/app/config/settings.json" }, exposedirectories={ "/path/to/models": "/app/models" # Read-only }, exposedirectoriesrw={ "./output": "/app/output" # Read-write } ) as sandbox:

result = sandbox.run("""
import pandas as pd
import json
import os

# Read exposed files
df = pd.read_csv('/app/data/input.csv')
with open('/app/config/settings.json', 'r') as f:
    config = json.load(f)

# List available models
models = os.listdir('/app/models')
print(f"Available models: {models}")

# Process data and save results
summary = df.describe()
summary.to_csv('/app/output/analysis_results.csv')

# Save processing log
with open('/app/output/log.txt', 'w') as f:
    f.write(f"Processed {len(df)} rows with config: {config}")

print(f"Processed {len(df)} rows successfully")
""")

print(result.stdout)

```

Temporary File Creation

```python with BioCageManager() as sandbox: # Create temporary files with custom content csv_data = """name,age,city Alice,25,New York Bob,30,San Francisco Charlie,35,Boston"""

csv_path = sandbox.create_temp_file(csv_data, suffix=".csv")

result = sandbox.run(f"""
import pandas as pd

# Load and analyze the temporary file
df = pd.read_csv('{csv_path}')
print(f"Loaded {len(df)} rows")
print(df.to_string())

# Calculate statistics
avg_age = df['age'].mean()
print(f"Average age: {avg_age:.1f}")
""")

print(result.stdout)
# Temporary files automatically cleaned up

```

🔧 Advanced Features

Resource Management

```python

Configure container resources

sandbox = BioCageManager() sandbox.startcontainer( memorylimit="4g", # 4GB memory limit cpulimit="8.0", # 8 CPU cores networkaccess=False # Disabled by default for security )

Monitor container information

info = sandbox.getcontainerinfo() print(f"Container ID: {info['containerid'][:12]}") print(f"Running: {info['isrunning']}") print(f"Exposed paths: {len(info['exposed_paths'])}")

sandbox.stop_container() ```

Error Handling and Debugging

```python def safeexecute(code, description=""): """Execute code with comprehensive error handling.""" with BioCageManager() as sandbox: result = sandbox.run(code, timeout=30, shutdownon_failure=False)

    if result.success:
        return f"✅ {description}: {result.stdout.strip()}"
    else:
        # Categorize errors for better debugging
        stderr_lower = result.stderr.lower()
        if "syntaxerror" in stderr_lower:
            return f"❌ Syntax Error: {result.stderr}\n💡 Check parentheses, quotes, and indentation"
        elif "nameerror" in stderr_lower:
            return f"❌ Name Error: {result.stderr}\n💡 Variable not defined"
        elif "importerror" in stderr_lower:
            return f"❌ Import Error: {result.stderr}\n💡 Module not available"
        else:
            return f"❌ {description} failed: {result.stderr.strip()}"

Test different scenarios

print(safeexecute("print('Hello World!')", "Basic execution")) print(safeexecute("print(undefinedvar)", "Variable error")) print(safeexecute("import nonexistent_module", "Import error")) ```

Multi-Step Data Analysis Workflow

```python def dataanalysispipeline(datapath, outputdir): """Complete data analysis with state persistence."""

with BioCageManager().configure_context_manager(
    memory_limit="4g",
    expose_files={data_path: "/app/data/dataset.csv"},
    expose_directories_rw={output_dir: "/app/output"}
) as sandbox:

    # Step 1: Load and explore
    sandbox.run("""
    import pandas as pd
    import numpy as np
    import matplotlib.pyplot as plt

    df = pd.read_csv('/app/data/dataset.csv')
    print(f"Dataset shape: {df.shape}")
    print(f"Columns: {list(df.columns)}")
    """)

    # Step 2: Clean data (state persists)
    sandbox.run("""
    df_clean = df.dropna()
    print(f"After cleaning: {df_clean.shape}")

    with open('/app/output/cleaning_report.txt', 'w') as f:
        f.write(f"Original: {df.shape}\\nCleaned: {df_clean.shape}\\n")
    """)

    # Step 3: Analysis (all variables still available)
    result = sandbox.run("""
    summary = df_clean.describe()
    summary.to_csv('/app/output/summary_statistics.csv')

    print(f"Analysis completed for {len(df_clean)} rows")
    """)

    return result.stdout

Usage

result = dataanalysispipeline('/path/to/data.csv', './output')

```

📋 Execution Results

All executions return a comprehensive SandboxExecutionResult object:

```python result = sandbox.run('print("Hello"); import sys; print(sys.version)')

print(f"Success: {result.success}") # True/False print(f"Output: {result.stdout}") # "Hello\n3.11.0..." print(f"Errors: {result.stderr}") # Any error messages print(f"Exit code: {result.exitcode}") # 0 for success print(f"Time: {result.executiontime:.3f}s") # Execution duration

Convert to dictionary for JSON serialization

resultdict = result.todict() ```

🐳 Docker Usage

You can also use BioCage directly with Docker:

```bash

Execute code via stdin

echo 'print("Hello from BioCage!")' | docker run --rm -i biocage:latest

Execute via environment variable

docker run --rm -e PYTHONCODE="import numpy as np; print(np.version_)" biocage:latest

With resource limits

docker run --rm -i --memory="1g" --cpus="2.0" biocage:latest ```

🏗️ Building Custom Images

Customize the Docker environment for your specific needs:

1. Edit dependencies in python_docker/pyproject.toml: toml [project] dependencies = [ "numpy>=1.24.0", "pandas>=2.0.0", "scikit-learn>=1.3.0", "your-custom-package>=1.0.0", ]

2. Generate requirements and build: bash cd python_docker uv pip compile pyproject.toml -o requirements.txt ./build.sh

🛡️ Security Features

BioCage is designed with security as a first-class concern:

• Container Isolation: Complete separation from host system
• No Network Access: Internet disabled by default during execution
• Resource Limits: Memory, CPU, and execution time controls
• Read-Only Filesystem: Prevents unauthorized file modifications
• Timeout Controls: Automatic termination of long-running processes
• Privilege Restrictions: Containers run with minimal privileges

🎯 Use Cases

AI/LLM Integration

• Code Generation: Safely execute AI-generated Python code
• Interactive Assistants: Build chatbots that can run and debug code
• Automated Testing: Validate generated code snippets

Education & Training

• Online Learning: Secure code execution for student submissions
• Coding Challenges: Isolated environment for competitive programming
• Tutorial Platforms: Interactive Python learning experiences

Research & Development

• Experiment Automation: Reproducible research environments
• Data Processing: Secure analysis of sensitive datasets
• Algorithm Testing: Isolated testing of new algorithms

Development Workflows

• CI/CD Pipelines: Safe testing of code changes
• Code Review: Automated validation of pull requests
• Prototyping: Quick testing of code concepts

📚 Documentation

• BioCageManager Features & Usage - Comprehensive guide to advanced features
• Docker Setup Guide - Complete Docker configuration and deployment
• API Reference - Detailed API documentation

🔗 Links

• GitHub Repository: https://github.com/biocypher/biocage
• Documentation: https://biocypher.github.io/biocage
• PyPI Package: https://pypi.org/project/BioCage
• Issues & Support: https://github.com/biocypher/biocage/issues

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

---

BioCage: Safe, stateful, and powerful Python execution for the AI era.