onit-sandbox

A Docker-based code execution sandbox MCP server for safe Python execution. Gives LLM agents an isolated environment where they can install packages, run code, and produce artifacts — without touching the host system.

Why onit-sandbox?

Traditional bash-based MCP tools block package managers and restrict operations. onit-sandbox lifts those restrictions safely by running everything inside per-session Docker containers with resource limits and network isolation.

• Install any package — pip install numpy matplotlib torch just works
• Run full projects — execute scripts, run tests, build simulations
• Stay secure — containers are resource-limited, network-isolated, and non-root

Architecture

┌──────────────────────────────────────┐
│  LLM Agent (chat loop)              │
│  ┌────────────────────────────────┐  │
│  │ SandboxMCPServer               │  │
│  │  install_packages              │  │
│  │  run_code                      │  │
│  │  sandbox_status                │  │
│  └──────────┬─────────────────────┘  │
│             │ Docker CLI              │
│  ┌──────────▼─────────────────────┐  │
│  │ Docker Container (per-session) │  │
│  │  - python:3.12-slim base       │  │
│  │  - Full pip access             │  │
│  │  - Workspace bind-mounted      │  │
│  │  - CPU/mem/network limits      │  │
│  │  - Auto-cleanup on stop        │  │
│  └────────────────────────────────┘  │
└──────────────────────────────────────┘

Installation

From PyPI

pip install onit-sandbox

From source

git clone https://github.com/sibyl-oracles/onit-sandbox.git
cd onit-sandbox
pip install -e .

Prerequisites

• Python 3.10+
• Docker — install from docker.com

Docker Image

The sandbox runs code inside a custom Docker image pre-loaded with common scientific packages.

Pull from GitHub Container Registry

docker pull ghcr.io/sibyl-oracles/onit-sandbox:latest

Then set the image name so the server uses it:

export SANDBOX_IMAGE=ghcr.io/sibyl-oracles/onit-sandbox:latest

Build locally

cd docker
chmod +x build.sh
./build.sh

This builds onit-sandbox:latest locally. The image includes:

Fallback

If no custom image is found, the server falls back to python:3.12-slim automatically. Packages can still be installed at runtime via install_packages.

Quick Start

# Start the MCP server (background)
onit-sandbox start

# Start in foreground (useful for debugging)
onit-sandbox start --foreground

# Check status
onit-sandbox status

# Stop the server
onit-sandbox stop

The server runs on http://0.0.0.0:18205/sse by default.

MCP Tools

install_packages

Install Python packages inside the sandbox via pip. Network is temporarily enabled for PyPI access, then disabled again.

{
  "packages": "numpy matplotlib scipy",
  "session_id": "my-session"
}

run_code

Execute shell commands inside the sandbox. Files written by write_file are available in the working directory. Output is captured and returned (truncated to 10 KB).

{
  "command": "python simulation.py",
  "timeout": 120,
  "session_id": "my-session"
}

sandbox_status

Check sandbox state — container health, Python version, installed packages, disk usage, uptime, and GPU availability.

{
  "session_id": "my-session"
}

Configuration

CLI Options

onit-sandbox start [OPTIONS]

  --host         Host to bind to (default: 0.0.0.0)
  --port         Port to bind to (default: 18205)
  --transport    sse or stdio (default: sse)
  --foreground   Run in foreground
  --verbose      Enable verbose logging
  --data-path    Workspace data directory (default: /tmp/onit/data)

Environment Variables

YAML Configuration

# configs/default.yaml
server:
  name: SandboxMCPServer
  host: 0.0.0.0
  port: 18205
  transport: sse

docker:
  sandbox_image: onit-sandbox:latest
  memory_limit: 512m
  cpu_quota: 100000
  pids_limit: 100
  network_disabled_default: true

Integration with OnIt

Add to your OnIt configs/default.yaml:

mcp_servers:
  - name: SandboxMCPServer
    description: Python code execution sandbox with package installation
    url: http://127.0.0.1:18205/sse
    enabled: true

Programmatic Usage

from onit_sandbox.mcp_server import run, cleanup_sandbox

# Start the server
run(transport="sse", host="0.0.0.0", port=18205)

# Cleanup a session's container
cleanup_sandbox(session_id="my-session")

Security

Isolation Features

What's Blocked

• Direct host filesystem access (only mounted workspace)
• Root access inside container
• Network access during code execution
• Unlimited resource consumption

What's Allowed

• Full PyPI access during install_packages
• Read/write to mounted workspace
• Python execution with any installed packages
• Shell commands within resource limits

Development

Setup

# Clone and install with dev dependencies
git clone https://github.com/sibyl-oracles/onit-sandbox.git
cd onit-sandbox
pip install -e ".[dev]"

# Or use the setup script (creates venv, builds Docker image)
chmod +x setup.sh
./setup.sh

Running Tests

# All tests
pytest tests/ -v

# Skip Docker-dependent tests
pytest tests/ -v -k "not Docker"

Code Quality

black src/ tests/        # Format
ruff check src/ tests/   # Lint
mypy src/                # Type check

Publishing a Release

1. Update the version in pyproject.toml
2. Create a GitHub release with a tag matching the version (e.g., v0.1.0)
3. The publish workflow automatically builds and uploads to PyPI
4. The docker workflow automatically builds and pushes the container image to GHCR

Troubleshooting

License

Apache License 2.0 — see LICENSE for details.