pi-python-sandbox

A Pi extension that runs Python code inside an isolated Docker container with the current working directory mounted as read-only.

What it does

Registers a python_sandbox tool in Pi that executes Python snippets in a disposable python:3-slim container. The host project directory is bound into the container in read-only mode, so the code can inspect files but cannot modify them on disk.

Prerequisites

• Docker daemon running and accessible via /var/run/docker.sock
• Node.js 18+
• Pi

Installation

npm install

Usage

As a Pi extension

When Pi loads this extension, the python_sandbox tool is automatically registered. You can invoke it from natural language or by using the tool directly:

python_sandbox({ "command": "print('hello')" })

Architecture

src/
├── index.ts      — Pi extension entry point; registers the python_sandbox tool
└── tools.ts      — Docker client logic (image pull, container lifecycle)

• src/index.ts — Defines the python_sandbox tool schema and delegates execution to startSandbox().
• src/tools.ts — Handles Docker operations: image existence check, pulling if needed, creating/starting a container, collecting logs, and cleanup.

Development

Clone the repo, install dependencies, and run the extension in Pi:

pi -e .

License

MIT