Belgie: The generative AI/UI sandbox for python

Belgie is a sandboxed TypeScript environment for Python that lets you build React MCP Apps and have agents write code in a sandbox.

• MCP Apps: Attach React widgets to Python MCP tools in one project.
• AI agents: Sandboxed run_code so Pydantic AI and LangChain can run TypeScript and TSX.
• Inline React widgets: Return self-contained HTML from run_code with @belgie/render.
• Sandbox: Deno is bundled, so you do not need to install Node.js.

Installation

uv add belgie
uvx library-skills install  # optional: install the use-belgie skill for Cursor, Codex, Claude, etc.

For MCP Apps, install the MCP and CLI extras:

uv add "belgie[mcp,cli]"

MCP Apps

Skip the second package manager. Attach a React widget to a Python MCP tool. BelgieExtension starts Vite in the background for development and runs a one-time production build.

from datetime import UTC, datetime
from pathlib import Path

from mcp.server import MCPServer

from belgie.mcp import BelgieExtension

belgie = BelgieExtension(project=".")


@belgie.tool(
    widget=Path("src/widgets/get-time/widget.tsx"),
    name="get-time",
    title="Get Time",
    description="Get the current server time in ISO 8601 format.",
)
def get_time() -> dict[str, str]:
    return {"time": datetime.now(tz=UTC).isoformat()}


mcp = MCPServer(name="Get Time Server", extensions=[belgie])

The widget is a normal React entry. @belgie/mcp connects the MCP Apps host and surfaces the opening tool result:

import { Widget, useToolResult } from "@belgie/mcp";
import { getTime } from "@widgets/tools";

function AppView() {
  const { data, isLoading, execute } = useToolResult(getTime);
  return (
    <main>
      <p>{data?.time ?? (isLoading ? "Waiting..." : "No time returned.")}</p>
      <button onClick={() => void execute()}>Refresh</button>
    </main>
  );
}

export default function GetTime() {
  return (
    <Widget metadata={{ name: "Get Time", version: "1.0.0" }}>
      <AppView />
    </Widget>
  );
}

Declare JS deps under [tool.belgie.dependencies], then:

uv run belgie lock
uv run belgie install
# start your MCP server; Belgie starts Vite with widget HMR

Pass build=False to BelgieExtension when Vite is managed separately or production assets are already built.

Runnable projects:

• mcp: Minimal MCP Apps widget.
• shadcn: Same pattern with Tailwind CSS and shadcn/ui.
• tanstack: TanStack Start SPA and MCP widget served together through FastAPI.

AI agents

When an agent needs an npm package, a browser-style API, or a JS-side transform, give it run_code. Belgie executes the TypeScript, JavaScript, or TSX in the embedded Deno sandbox. No separate Node install.

Pydantic AI

Install with uv add "belgie[pydantic-ai]", set OPENAI_API_KEY, then:

from pydantic_ai import Agent

from belgie.pydantic_ai import BelgieCapability

agent = Agent("openai:gpt-5", capabilities=[BelgieCapability()])

result = agent.run_sync(
    "Convert 'foo-bar' to camelCase using TypeScript and the camelcase npm package.",
)
print(result.output)

See examples/ai/pydantic-ai.

LangChain

Install with uv add "belgie[langchain]", set OPENAI_API_KEY, then:

from langchain.agents import create_agent

from belgie.langchain import BelgieMiddleware

agent = create_agent(
    model="openai:gpt-5",
    tools=[],
    middleware=[BelgieMiddleware()],
    system_prompt="You can execute JS/TS in a Deno sandbox with run_code.",
)

result = agent.invoke(
    {
        "messages": [
            (
                "user",
                "Convert 'foo-bar' to camelCase using TypeScript and the camelcase npm package.",
            ),
        ],
    },
)
print(result["messages"][-1].content)

See examples/ai/langchain.

Under the hood: Deno in Python

MCP Apps and agent run_code both use Belgie’s embedded Deno runtime. Call it directly when you need JS/TS from Python without MCP or an agent framework:

• Scripts: Inline or file-based JS/TS with Runtime and Script, sync or async.
• Inline dependencies: Import npm, JSR, and URL modules from source.
• Environments: Lockfiles, custom cache/options, local packages, and Command for npm binaries (Vite, esbuild, etc.).
• Data bridge: Pass JSON-safe dicts, lists, and primitives across the boundary.

Runtime permissions

RuntimePermissions gates Deno APIs and every host-backed module read, including static and dynamic imports, JSON modules, and Node require(). File entrypoints created with Script.from_file and command entrypoints must be covered by allow_read; inline and in-memory sources do not need a host read grant. Belgie-managed npm packages are available to the module loader without adding their node_modules or cache roots to the runtime's general read grants. Package imports therefore work in restricted runtimes, while Deno.readFile, arbitrary absolute file: URLs, and other direct host reads remain subject to the caller's allow_read and deny_read settings.

import asyncio

from belgie import Runtime, Script

script = Script[[str], str](
    """
import camelcase from "npm:camelcase@8.0.0";

export default function run(input: string): string {
  return camelcase(input);
}
"""
)


async def main() -> None:
    async with Runtime() as run:
        print(await run(script)("foo-bar"))  # prints: fooBar


asyncio.run(main())

Inline widget rendering

Pydantic AI and LangChain agents can return a complete inline React widget through the same run_code tool. The agent writes one TSX module and imports the standalone renderer:

import { render } from "npm:@belgie/render";

function Widget() {
  return <main>Hello from Belgie</main>;
}

export default function run() {
  return render({
    widget: <Widget />,
    plugins: [],
  });
}

render() requests HTML from a Belgie-owned renderer side-channel (not from the model-visible Deno worker). The agent Script stays workspace-restricted — no host /etc//proc, allow_sys, or allow_ffi — while Vite runs only in that host-mediated worker (workspace FFI/sys/write, no host path grants) and returns one self-contained HTML string with inline JavaScript, CSS, and assets. Package imports are supported. Relative host-file imports are intentionally unavailable, and Vite plugins run only during the server build, where their factories, hooks, and imports have the renderer worker's broader permissions. Treat them as reviewed application code and use plugins: [] for untrusted agents. Plugin-only imports are removed from the browser bundle. This API is independent from @belgie/mcp and its path-based widget.tsx development and production flow.

Examples

Small, runnable projects. Each focuses on one capability.

UI

• mcp: MCP Apps extension with a React widget built through Belgie.
• shadcn: MCP Apps widget styled with Tailwind CSS and shadcn/ui.
• tanstack: TanStack Start SPA and MCP widget served together through FastAPI.

AI

• pydantic-ai: Pydantic AI agent with BelgieCapability() for sandboxed JS/TS/TSX execution.
• langchain: LangChain agent with BelgieMiddleware() for sandboxed JS/TS/TSX execution.

Basic

• simple: Async Runtime with a TypeScript file on disk.
• inline-deps: Direct npm:, jsr:, and URL imports in a script.
• jsr-deps: JSR packages declared through an explicit Environment.
• pyproject: Manage project package dependencies with belgie[cli] and [tool.belgie.dependencies].
• environment: Sync and async Environment setup with path.
• commands: npm package binaries via Runtime and Command.

For deeper integration guidance, optionally install the use-belgie skill with uvx library-skills install.