pi-monty-sandbox

Safe, high-performance Python execution sandbox extension for Pi Coding Agent powered by Pydantic Monty (a memory-safe sandboxed Python VM written in Rust).

Available on the Pi Package Catalog.

Features

• Strict Isolation: Code executes inside a crash-isolated subprocess sandbox with no direct access to host network, host environment variables, or host filesystem.
• Stateful REPL: Variables, functions, and imports persist across tool calls within a session.
• Sub-millisecond Speed: Near-instant cold start (~5ms) compared to seconds for Docker or micro-VMs.
• Self-Healing Guidance: Clear actionable hints when code exceeds sandbox capabilities, steering the LLM to the right solution.
• Resource Limits: Configurable execution timeouts and memory limits enforced inside the Rust VM.
• Type Checking: Automatic syntax and type checking diagnostics via Monty (ty).
• Live Output Streaming: Captures print() stdout/stderr and streams it to the Pi TUI.
• Custom TUI Rendering: Styled execution headers, progress indicators, and traceback rendering.
• Convenient Controls: Reset the REPL session anytime via the /pyreset slash command or reset_session: true argument.
• Read-only Bridge (opt-in): pi's own read/grep/find/ls tools become callable Python functions inside the sandbox (await grep("TODO")) — loop, filter and aggregate workspace data in one snippet; intermediate results never enter model context, only what the code print()s. Statically type-checked against bridge stubs before execution.

Installation

Install globally into Pi:

pi install npm:pi-monty-sandbox

Or install project-locally:

pi install npm:pi-monty-sandbox -l

Or test instantly without installing:

pi -e npm:pi-monty-sandbox

When to Use: python_sandbox vs bash

Task	Recommended Tool	Why
Math calculations & combinatorics	python_sandbox	Sub-millisecond execution, zero side effects, no subprocess overhead
Algorithmic reasoning & logic verification	python_sandbox	Safe scratchpad, stateful across multi-turn prompts
JSON / String parsing & transformations	python_sandbox	Instant in-memory data processing
Regex testing & text manipulation	python_sandbox	Isolated, no risk of runaway processes
Multi-file search / aggregation (count, filter, compare across many files)	python_sandbox (with bridge)	Bridged grep/read/find/ls run in a loop inside one snippet; only the aggregated print() output enters context — a task that needs 20 direct tool round-trips becomes one call
Async logic verification (asyncio.run, gather)	python_sandbox	Built-in async coroutine support
Scripts requiring external packages (numpy, pandas, requests)	bash	Monty sandbox has no pip package access
Workspace file edits / Git operations	bash	Monty sandbox has no host filesystem access
Network requests / API scraping	bash	Monty sandbox has no network access

Supported Python Subset

Monty is a custom, memory-safe Python interpreter written in Rust. It supports Python core syntax with the following subset:

• Supported Standard Library Modules: math, re, json, itertools, collections (deque, Counter, defaultdict, namedtuple), dataclasses (@dataclass), datetime, functools (reduce, partial), pathlib, asyncio (run, gather), base64, binascii, os (path functions), sys, typing, unicodedata.
• Unsupported Modules: random, time, string, csv, copy, heapq, hashlib, uuid, io, urllib, enum (use bash if needed).
• Unsupported Syntax: No class inheritance (class A(B)), no method decorators (@property, @classmethod), no generators (yield), no del keyword (use .pop()).

Configuration

Optional features are controlled by environment variables set where pi runs (e.g. in your shell profile or ~/.pi/agent/.env):

Variable	Default	Effect
PI_MONTY_BRIDGE=1	off	Bridge pi's read-only tools (read, grep, find, ls) into the sandbox as Python functions. Only what the code print()s returns to the model; every bridged call is logged as a [bridge] name(args) line in the streamed output. Default timeout_ms rises to 15000 while enabled.
PI_MONTY_MOUNT_WORKSPACE=1	off	Mount the workspace directory read-only at /workspace, so plain open()/os.listdir work against project files. Writes raise PermissionError. Independent of the bridge.

With the bridge enabled, the model is told it can call await read(path, offset, limit), await grep(pattern, path=..., glob=..., ignoreCase=..., literal=..., context=..., limit=...), await find(pattern, path=..., limit=...), await ls(path=..., limit=...) — positional arguments first, keyword arguments after. Bridge calls are type-checked before execution via monty's ty against generated async def stubs, so wrong argument types fail as compiler diagnostics instead of tracebacks.

Example:

# One snippet instead of ~30 direct tool round-trips:
import re
todos = await grep("TODO|FIXME", path="src")
counts = {}
for line in todos.splitlines():
    file = line.split(":")[0]
    counts[file] = counts.get(file, 0) + 1
for f, n in sorted(counts.items(), key=lambda kv: -kv[1]):
    print(f"{n:3} {f}")

Tool Specification: python_sandbox

Parameters

Parameter	Type	Description	Default
code	string	Pure Python code snippet to execute	Required
timeout_ms	integer	Execution timeout in milliseconds (max 30000)	5000
reset_session	boolean	Clear variables and start a fresh REPL session	false

Commands

• /pyreset: Resets the Python REPL sandbox session (clearing all defined variables and imported modules).

Example Usage in Pi

Ask the agent:

"Calculate 2^256 mod 1000000007 using python_sandbox."

Or maintain state across turns:

1. "Define a function calc_pi(n) in python_sandbox."
2. "Call calc_pi(1000) and print the result."

Security Model

Pi by design has no built-in sandboxing (built-in bash and file tools run with host user privileges). pi-monty-sandbox provides a dedicated safe computing layer for mathematical calculations, data parsing, algorithmic problem solving, and untrusted Python execution.

The optional read-only bridge does not expand the attack surface: it exposes exactly the tools the agent can already invoke directly (read/grep/find/ls), just callable from Python code — so loops over many calls cost zero extra model round-trips. Mutating tools (bash, edit, write), environment variables, and network are never bridged; the workspace mount is enforced read-only by monty's Rust VM.

License

MIT