Parselbox

<!-- mcp-name: io.github.thesanjeetc/parselbox -->
![Parselbox SDK](https://github.com/thesanjeetc/Parselbox/blob/main/assets/parselbox-dark.png#gh-dark-mode-only)
![Parselbox SDK](https://github.com/thesanjeetc/Parselbox/blob/main/assets/parselbox-light.png#gh-light-mode-only)

<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](https://deno.com/) and [Pyodide](https://pyodide.org/en/stable/).

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

> [!TIP]
> Drop the [Parselbox MCP](#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.

## 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](#quick-start)
  - [Parselbox API](#parselbox-api)
  - [Parselbox MCP](#parselbox-mcp)
  - [Parselbox Agents](#parselbox-agents)
- [User Guide](#user-guide)
  - [Tools as Code](#1-tools-as-code)
  - [Background Tasks](#2-background-tasks)
  - [Filesystem Integration](#3-filesystem-integration)
  - [Packages & Networking](#4-packages--networking)
  - [JavaScript Interop](#5-javascript-interop)
  - [WASM Tools](#6-wasm-tools)
  - [Progressive Disclosure](#7-progressive-disclosure)
  - [Generative UI](#8-generative-ui)
  - [Sandbox Hooks](#9-sandbox-hooks)
- [Configuration Reference](#configuration-reference)
- [Architecture](#architecture)
- [Security](#security)
- [Related Work](#related-work)

## Quick Start

Parselbox uses [**Deno**](https://deno.com) for the secure sandbox runtime.

**1. Install Deno**

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

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

**2. Install Parselbox**

```bash
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:**

```python
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:**

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

#### HTTP

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

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

#### Full Example

```bash
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

```python
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:

```python
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 P