denosaurs

A JS sandbox for AI agents

Run untrusted, LLM-generated JavaScript safely in Python — real V8, real isolation, real tool-calling.

   ___
 _/ o \
 \____/
  |  |
   \  \
   |  |
    \  \
   /    \__________________
  /                        \________
  |                                 \____________
   \___________________                    ______/
       | |   | |       \__________________/
       | |   | |           | |   | |
       |_|   |_|           |_|   |_|

Documentation · Examples · Issues

16-18x faster repeat execution via context-isolated isolate pooling — ~3 ms cold Runtime() start vs. ~167-185 µs per pooled IsolatePool checkout+eval, measured with Criterion and pytest-benchmark, with a dedicated test proving no state leaks between checkouts. Proven, not claimed — see BENCHMARKS.md.

What this is

Agent frameworks and tool-execution runtimes increasingly need to run JavaScript the model itself wrote — a code-generation step, a small data transform, a "call this JS snippet to compute the answer" tool. That code is untrusted by construction. denosaurs embeds a real V8 isolate per runtime (via Rust/PyO3) so that code runs with no filesystem, no network, and no ambient Node.js APIs by default, with heap and wall-clock limits you set, and a real way to kill it if it doesn't stop on its own.

It is not a general "embed any JS anywhere" library and not a JS interpreter reimplemented in Python — it's V8, the same engine behind Chrome and Node.js, so the JS your model writes actually behaves like JS.

import denosaurs

denosaurs.bind_function("add", lambda a, b: a + b)
print(denosaurs.eval("add(2, 3)"))  # 5

Why it's different

• Real V8, not a toy interpreter. Every language quirk, every standard library method, every performance characteristic your model expects from "JavaScript" is the real thing.
• Cross-thread termination that actually works. A watchdog thread calling .terminate() on a runaway while(true){} used to panic instead of stopping the code (pyo3_runtime.PanicException: Runtime is unsendable, but sent to another thread) — a real bug in the upstream design that meant a stuck agent tool call couldn't be killed from outside. TerminationHandle fixes this: it exposes only the Send + Sync part of V8's isolate handle, so a watchdog on a separate thread can interrupt execution safely. See PATCH.md for the full root cause and proof; tests/test_termination_handle.py is the regression test.
• Context-isolated pooling, so speed doesn't cost you isolation. A cold V8 isolate costs ~3 ms to create; IsolatePool keeps a small set of them warm and hands out a brand-new, empty V8 Context on every checkout — the isolate is reused, but no JS-visible global state (globalThis, etc.) ever survives from one caller to the next, even when they land on the same underlying isolate. Measured: ~3 ms cold-start → ~170-185 µs pooled, ~16-18x, with a dedicated test proving a globalThis value set in one checkout is gone (typeof x === 'undefined') in the next. See BENCHMARKS.md and src/runtime/pool.rs for the numbers and the reasoning.
• A host-callback bridge for tool-calling from JS. bind_function/ bind_object let the sandboxed JS call back into Python — the primitive an agent needs when the model's JS wants to invoke a real tool, not just compute a value.

Get Started

pip install denosaurs  # or uv pip install denosaurs

Requires Python 3.10+ on macOS or Linux. denosaurs is experimental — expect breaking changes between versions.

Quickstart: sandboxed eval, tool-calling, and a timeout

import asyncio

from denosaurs import Runtime, RuntimeConfig

# Cap memory; the runtime terminates itself if JS tries to exceed it.
config = RuntimeConfig(max_heap_size=10 * 1024 * 1024)  # 10 MB


async def main():
    with Runtime(config) as runtime:
        # The tool-calling primitive: expose a Python function to the sandboxed JS.
        def get_weather(city: str) -> str:
            return f"72F and sunny in {city}"

        runtime.bind_function("getWeather", get_weather)

        # Model-generated JS calling back into your tool.
        result = runtime.eval("getWeather('Zurich')")
        print(result)  # "72F and sunny in Zurich"

        # Enforce a wall-clock timeout on code that might not terminate.
        try:
            await runtime.eval_async("while (true) {}", timeout=2.0)
        except Exception as exc:
            print(f"killed a runaway eval after 2s: {exc}")


asyncio.run(main())

Running an untrusted sync eval() you can't await? Grab a TerminationHandle before the call and .terminate() it from a watchdog thread — see tests/test_termination_handle.py for the exact pattern (and the bug it fixed, in PATCH.md).

For a fast path when you're running many short-lived, independent snippets (e.g. one per agent turn) and don't need bind_function/modules for that particular call, check out an isolate from a warm IsolatePool instead of paying full cold-start cost each time:

from denosaurs import IsolatePool

pool = IsolatePool(size=4)
with pool.checkout() as isolate:
    print(isolate.eval("1 + 41"))  # 42

Integrations

• FastMCP tool bridge - expose FastMCP tools to sandboxed JS via bind_function and an in-process fastmcp.Client
• pydantic-ai "code mode" agent - an agent tool where the model submits one JS batch script instead of many separate tool calls, run safely with a timeout
• Vendored npm libraries - run real npm document-generation libraries (pptxgenjs, pdf-lib) from their browser bundles inside the sandbox; see the guide for what makes a library a good candidate
• Arrow IPC dataframes - move 100k+ row tables into the sandbox as Arrow IPC bytes instead of JSON objects (5 ms vs 253 ms, and it works at the default 10 MB serialization limit that rejects the JSON payload); see the guide

Documentation

• Quick Start
• Concepts: runtimes, type conversion, resource controls
• Guides: binding functions, module loading, snapshots
• Use cases: AI agent sandboxes, workflow runners, plugin systems
• API reference
• Benchmarks — measured, reproducible numbers, including the pooling comparison above