Ipybox MCP Server: IPython Docker Execution Sandbox

Overview

Ipybox MCP Server provides a simple, developer-friendly HTTP service that runs IPython in a Docker-backed sandbox. It exposes a stateful execution environment where successive snippets share in-memory state (variables, imported modules, open file handles) while isolating execution inside containers to reduce risk from untrusted code. The server is designed for integrations such as language-model tools, CI helpers, or remote code evaluation in applications that need repeatable, interactive Python execution.

The server focuses on a practical balance of usability and safety: it gives you a persistent Python kernel per session, file upload/download for inputs and artifacts, and configurable network/resource controls so you can limit egress and CPU/memory usage. It is not a replacement for hardened multi-tenant platforms, but a compact, configurable sandbox suitable for development and controlled deployments.

Features

• Stateful IPython execution: run snippets that share session state (variables, imports).
• Docker isolation: each session or execution runs inside a container for process and filesystem isolation.
• File transfer: upload inputs and download artifacts from the sandboxed filesystem.
• Configurable network access: enable/disable or whitelist network egress for containers.
• Resource limits: set container CPU, memory, and execution timeouts.
• Simple HTTP API: endpoints to create sessions, run code, transfer files, and query status.
• Designed for programmatic integration (CLI, webhooks, LLM tools).

Installation / Configuration

Prerequisites: Docker (or a Docker-compatible runtime) and git.

Clone and build the project:

git clone https://github.com/gradion-ai/ipybox.git
cd ipybox
docker build -t ipybox .

Run the server with basic defaults:

docker run -d --name ipybox -p 8080:8080 \
  -v /var/ipybox_workspace:/workspace \
  -e MCP_PORT=8080 \
  -e MCP_MAX_RUNTIME=30 \
  ipybox

Recommended environment variables (examples):

• MCP_PORT: HTTP port the server listens on (default 8080).
• MCP_MAX_RUNTIME: per-execution timeout in seconds.
• MCP_ALLOW_NETWORK: “true”/“false” to enable egress; can also accept a whitelist specification.
• MCP_WORKDIR: default working directory inside containers.
• MCP_IMAGE: base image to use for execution containers (e.g., a Python/IPython image).

Example docker-compose service:

version: "3.8"
services:
  ipybox:
    image: gradion/ipybox:latest
    ports:
      - "8080:8080"
    volumes:
      - ./workspace:/workspace
    environment:
      MCP_PORT: "8080"
      MCP_MAX_RUNTIME: "60"
      MCP_ALLOW_NETWORK: "false"
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G

Notes:

• Use volume mounts to persist workspace files or to provide datasets.
• When disabling network access, test your base image to ensure required packages are preinstalled.

Available Resources

Typical HTTP endpoints exposed by the server (names and exact paths may vary by release):

Example: execute code in a session

curl -X POST "http://localhost:8080/execute" \
  -H "Content-Type: application/json" \
  -d '{"session":"default","code":"a = 1\\nprint(a + 2)"}'

Example: upload a file

curl -X POST "http://localhost:8080/files/upload?session=default" \
  -F "file=@./input.csv"

Example: download a file

curl "http://localhost:8080/files/download?session=default&path=results/output.csv" -o output.csv

Responses typically include execution stdout/stderr, any JSON metadata, and container status. Consult the running server’s /status endpoint for exact payload formats.

Use Cases

• Integrating a language model with a code execution tool: wire the MCP execute endpoint to an LLM tool integration so the model can run Python snippets with shared state (imports, variables) while sandboxing runs in Docker.

  • Workflow: create session → send code snippets → upload datasets → download results.

• Safe evaluation of user-submitted code in a controlled environment: use per-session Docker containers, set MCP_ALLOW_NETWORK=false, and enforce MCP_MAX_RUNTIME to reduce abuse risk.

  • Example: online explanation tools that run short analysis scripts on user data without exposing host resources.

• Reproducible data processing: mount datasets as volumes, run a chain of execution snippets to transform data while preserving session state and artifacts.

  • Example commands: upload pre-processing script, run steps, then download processed artifacts.

• Automated testing and experiment sandboxing: run test code, collect logs and outputs, and tear down containers programmatically via the API.

Getting Help and Contributing