Parselbox

<!-- mcp-name: io.github.thesanjeetc/parselbox -->

<div align="center">

Code. Filesystem. Context. Tools.<br/> What if agents had one tool to rule them all?

</div> <h4 align="center"> <a href="https://github.com/thesanjeetc/Parselbox/blob/main/LICENSE.md"> <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge"> </a> <a href="https://pypi.org/project/parselbox/"> <img alt="PyPI - Version" src="https://img.shields.io/pypi/v/parselbox?style=for-the-badge"> </a> <a href="https://github.com/thesanjeetc/Parselbox/actions/workflows/ci.yaml"> <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/thesanjeetc/Parselbox/ci.yaml?branch=main&style=for-the-badge&label=CI"> </a> </h4>

Parselbox is an embeddable Python runtime where AI agents call tools as code — MCP servers, APIs, and shells become native Python objects. Disk-backed workspace, packages, and networking built in; a single-process execution layer powered by Deno and Pyodide.

https://github.com/user-attachments/assets/d4e43d16-3aa3-4e29-83c7-a1d3885b8045

[!TIP] Drop the Parselbox MCP alongside existing MCP server configurations. Agents instantly get a Python runtime, MCP tools as code, support for skills and a disk-backed workspace.

Why Parselbox?

Parselbox packages programmatic tool calling as a local, open-source execution layer. Drop it into an existing MCP configuration with uvx, or embed the Python API into any agent stack.

Beyond code execution, Parselbox provides a stateful, disk-backed workspace with packages, controlled networking, background tasks and progressive discovery.

Deno + Pyodide provide a single-process runtime with explicit filesystem and network permissions — no containers or microVMs required. It also enables JavaScript/npm interoperability, WASM/WASI integration and generative UI through MCP Apps.

Why an execution layer?

Most agent stacks expose each capability as a separate tool. As integrations grow, tool schemas consume more context. The model must also carry intermediate results, transform data and route values between calls.

An execution layer moves orchestration out of the context window and into code. Capabilities are discovered on demand, then composed with full control flow. A single execution can coordinate multiple tools while variables, state and files remain inside the runtime.

The result is less context bloat, fewer model-to-tool round trips and complex workflows expressed as code rather than chains of individual calls.

Features

🔒 Secure Isolation

No containers, no VMs — just a single, lightweight Deno + Pyodide process (~160 MB). Deno permissions, memory caps, timeouts, network allowlists. Snapshot caching and crash recovery.

🛠️ Tools as Code

MCP servers, REST + OpenAPI, GraphQL, shell, functions and classes — all native Python objects. Stateful across calls. Pydantic auto-conversion. Credentials stay on the host.

🐍 Polyglot Runtime

Full CPython with js() interop — use JS packages as native Python. require() for npm, local TypeScript, and .wasm modules. Virtual bash() for shell. Auto-install packages on import.

📦 WASM Tools

require() any .wasm — library exports become Python methods, WASI programs become callable commands; drop one in bin/ to run it from bash() too. In-process, inherits the sandbox's mounts and permissions, installs nothing on the host.

⚡ Background Tasks

Append .task() to any call — parallel fan-out with asyncio.gather, check progress, tail logs, drive interactive sessions with send(), await later.

📁 Filesystem Integration

Disk-backed workspace — host mounts (ro/rw), input files at /files/, outputs persisted to real directories. New and modified files are detected and returned per call.

🔍 Progressive Disclosure

help(), search(), inspect(), preview() — agents discover only what they need, when they need it.

🎨 Generative UI

display() renders HTML inline in the chat (MCP Apps), with Tailwind + daisyUI injected. Or serve a full app — built-in HTTP server with static files, live reload, file upload, and @api routes that compose across tools.

---

Contents

• Quick Start
  • Parselbox API
  • Parselbox MCP
  • Parselbox Agents
• User Guide
  • Tools as Code
  • Background Tasks
  • Filesystem Integration
  • Packages & Networking
  • JavaScript Interop
  • WASM Tools
  • Progressive Disclosure
  • Generative UI
  • Sandbox Hooks
• Configuration Reference
• Architecture
• Security
• Related Work

Quick Start

Parselbox uses Deno for the secure sandbox runtime.

1. Install Deno

# macOS / Linux
curl -fsSL https://deno.land/install.sh | sh

# Windows (PowerShell)
irm https://deno.land/install.ps1 | iex

2. Install Parselbox

pip install parselbox

Parselbox API

Wire any tool into the sandbox — MCP servers, REST/GraphQL, shells, host objects — and the agent calls them as native Python, composing them with real control flow over a disk-backed workspace and both the Python and npm package ecosystems.

Example:

import asyncio
import os
from textwrap import dedent
from parselbox import Parselbox
from parselbox.bridge import HTTPBridge, ShellBridge

class Analytics:
    def summarize(self, repos: list) -> dict:
        """Aggregate repo stats."""
        stars = [r["stars"] for r in repos]
        return {"count": len(repos), "avg_stars": round(sum(stars) / len(stars))}

config = {"mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}}}

async def main():
    async with Parselbox(
        mcp=config,
        context={
            "analytics": Analytics(),
            "github": HTTPBridge(base_url="https://api.github.com", token=os.environ["GITHUB_TOKEN"]),
            "sh": ShellBridge("bash"),
        },
        network=True,
        allow_runtime_packages=True,
        packages=["numpy", "npm:lodash"],
        output_dir="./workspace",
    ) as sbx:
        # Discover available tools
        await sbx.execute_code("sbx.search('navigate|get')")

        # Scrape Hacker News for GitHub links in a real browser
        await sbx.execute_code(dedent("""
            import re
            playwright.browser_navigate(url="https://news.ycombinator.com")
            text = playwright.browser_snapshot()
            repos = re.findall(r'github\\.com/([\\w.-]+/[\\w.-]+)', text)[:5]
        """))

        # Fetch star counts in parallel, then summarize via the context bridge
        await sbx.execute_code(dedent("""
            import asyncio
            results = await asyncio.gather(*[github.get.task(f"/repos/{r}") for r in repos])
            repo_data = [{"name": r["data"]["name"], "stars": r["data"]["stargazers_count"]}
                         for r in results if r.get("ok")]
            analytics.summarize(repo_data)
        """))

        # Chart it — matplotlib auto-installs on import
        result = await sbx.execute_code(dedent("""
            import matplotlib.pyplot as plt
            plt.barh([r["name"] for r in repo_data], [r["stars"] for r in repo_data])
            plt.savefig("chart.png")
        """))
        print(result.files)                  # ['chart.png']
        image = sbx.read_file("chart.png")
        # every result carries .output, .files, .stdout, .stderr, .error

        # Serve the whole sandbox as an MCP server
        await sbx.run_mcp()

asyncio.run(main())

Parselbox MCP

The Parselbox CLI runs a standalone MCP server — every sandbox option is available as a flag.

STDIO

[!TIP] The "loopback" trick:

1. Add the Parselbox MCP alongside your existing MCP servers.
2. Point --mcp at that same config file.
3. On startup, Parselbox connects to the other servers, exposes their tools inside the sandbox, and starts its own MCP server.

Don't worry — Parselbox detects and avoids connecting to itself. No infinite loops of doom.

Example:

{
  "mcpServers": {
    "github": {},
    "linear": {},
    "parselbox": {
      "command": "uvx",
      "args": ["parselbox", "--mcp", "/absolute/path/to/mcp.json"]
    }
  }
}

HTTP

uvx parselbox --mcp mcp.json --transport http --port 9000

{
  "mcpServers": {
    "parselbox": {
      "type": "http",
      "url": "http://localhost:9000/mcp"
    }
  }
}

Full Example

uvx parselbox \
  --mcp ./mcp.json \
  --transport http \
  --host 0.0.0.0 \
  --port 8080 \
  --file hello.txt \
  --mount ./datasets:/data:rw \
  --output-dir ./outputs \
  --packages pandas,matplotlib \
  --package-dir ./cache \
  --allow-runtime-packages \
  --network \
  --serve 3000 \
  --memory 2048 \
  --timeout 60 \
  --env MY_API_KEY=...

---

Parselbox Agents

import asyncio
from parselbox import Parselbox
from agents import Agent, Runner, function_tool

sandbox = Parselbox(
    mcp={"mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}}},
    output_dir="./outputs",
    allow_runtime_packages=True,
)

agent = Agent(
    name="Research Assistant",
    model="gpt-5.5",
    instructions=f"You are a world-class research assistant.\n\n{sandbox.get_prompt()}",
    tools=[function_tool(sandbox.get_tool())],
)

async def main():
    async with sandbox:
        result = await Runner.run(
            agent,
            "Scrape Wikipedia's 'List of highest-grossing films' with the Playwright MCP. "
            "Plot a bar chart of the top 10 and save it as ./plot.png",
            max_turns=30,
        )
        print(result.final_output)

asyncio.run(main())

User Guide

1. Tools as Code

The context bridge exposes host Python objects inside the sandbox:

• context — functions and namespaces as callable tools. Execution pauses, runs on host, returns result.
• globals — static values (strings, numbers, dicts) copied into the sandbox.
• mcp — MCP server config (dict or path). Appears as callable namespaces inside sandbox.

Plain classes are auto-wrapped — every public method becomes a callable tool; methods starting with _ stay private:

from parselbox import Parselbox

class Calculator:
    def add(self, a: float, b: float) -> float:
        """Add two numbers."""
        return a + b

async with Parselbox(context={"calc": Calculator()}) as sbx:
    await sbx.execute_code("calc.add(a=10, b=20)")

Subclass Bridge for nested namespaces (auto-crawled); annotate a parameter with a Pydantic model and passed dicts convert to it automatically:

from parselbox import Parselbox
from parselbox.bridge import Bridge
from pydantic import BaseModel

class Coordinate(BaseModel):
    x: float
    y: float
    z: float = 0.0

class Sensors(Bridge):
    def temperature(self) -> float:
        """Read temperature in celsius."""
        return 23.5

class Robot(Bridge):
    def __init__(self):
        self.sensors = Sensors()

    def move(self, to: Coordinate) -> dict:
        """Move robot to a position."""
        return {"position": [to.x, to.y, to.z], "status": "reached"}

async with Parselbox(context={"robot": Robot()}) as sbx:
    await sbx.execute_code("robot.move(to={'x': 1, 'y': 2})")
    await sbx