Agents increasingly answer questions by writing code: a data transform, a chart spec, a slide deck, a loop that calls your tools. That code is untrusted by construction. pydeno lets a Python program run it and get the result back, behind a boundary that holds even if the code is hostile.

from pydeno import IsolatedRuntime, RuntimeConfig

with IsolatedRuntime(RuntimeConfig(timeout=2.0), sandbox="require") as rt:
    rt.bind_function("lookup", lambda sku: {"A1": 3.5}[sku])   # the only thing the guest can call
    print(rt.eval("lookup('A1') * 2"))                          # 7.0
    rt.eval("new Array(2 ** 32 - 1).fill(0)")                   # WorkerCrashed. Your process is fine.

Why pydeno

Quickstart

pip install pydeno     # or: uv pip install pydeno     (Python 3.10+, macOS or Linux)

Tools the guest can call, with a total budget:

from pydeno import IsolatedRuntime, ToolBridge

bridge = ToolBridge({"get_weather": get_weather, "send_email": send_email}, max_calls=50)

with IsolatedRuntime(sandbox="require") as rt:
    bridge.attach(rt)
    rt.eval("tools.get_weather('Zurich')")

The call that exceeds max_calls never reaches your Python function; the guest gets a catchable ToolBudgetError. A Python exception inside a tool reaches JavaScript as a real Error whose name is the exception's class, so the model's code can branch on it. Use redact_host_errors=True if exception text must not reach the guest.

Make the easy path the safe one (the module-level helpers then use a sandboxed worker):

import pydeno

pydeno.configure_default_runtime(isolated=True, sandbox="require")
pydeno.eval("1 + 1")

Run real libraries. Many assume browser basics a bare isolate lacks. Opt in to a small, pure-JavaScript set (virtual-time timers, TextEncoder, btoa, Blob, EventTarget, AbortController, structuredClone) that never defines window or document:

from pydeno import IsolatedRuntime, RuntimeConfig, WEB_POLYFILLS

rt = IsolatedRuntime(RuntimeConfig(bootstrap=WEB_POLYFILLS))

Showcase: Python and JavaScript, both sandboxed

A model that writes code wants the best language for each half of the job: Python for wrangling data, JavaScript for what only the JS ecosystem does well. Pair pydeno with Monty (Pydantic's Python sandbox) and run both without trusting either, sharing one set of host tools and one call budget:

with Monty() as pool, pool.checkout() as py:                      # the model's Python, in Monty
    analysis = py.feed_run(model_python, external_lookup={"fetch_sales": fetch_sales})

with IsolatedRuntime(RuntimeConfig(bootstrap=WEB_POLYFILLS), sandbox="require") as js:
    js.bind_function("getAnalysis", lambda: analysis)             # hand the result across
    js.bind_function("fetch_sales", fetch_sales)                  # the same tool, same budget
    svg = await js.eval_async(model_javascript)                   # the model's JS, in pydeno

1. Python half, in Monty
  [python] best region: East (1750)
  [python] refused: PermissionError: Permission denied: '/etc/passwd'
2. JavaScript half, in pydeno
  [js]     refused: Evaluation failed: ReferenceError: fetch is not defined
  [js]     sandbox: seatbelt
3. wrote sales.svg (11021 bytes); tool calls used: 2 of 5

Python crunched the numbers; JavaScript drew the chart with Vega-Lite; each sandbox refused its own attempt to reach outside, and both drew on the same five-call tool budget. Full runnable example: examples/monty_and_pydeno.py.

More of the same: Python prepares, JavaScript builds

Monty is excellent at the data half, and the JavaScript ecosystem has libraries nothing in Python matches. Each example below is a complete, tested program: the model's Python runs in Monty, the model's JavaScript runs in pydeno, neither can reach your files, network or environment, and each test checks the answer against an independent computation (and Monty's against CPython's).

How fast are they together? One warm worker, median of three, on an Apple-silicon Mac, with V8 in its secure default (jitless) and with the JIT turned on:

Most turns finish in well under a second even in the secure mode; Monty's data half stays within about 1.1x of plain CPython. The JIT matters for compute-heavy JavaScript (layouts, raycasting), and it is exactly the part of V8 where most exploits live, which is why it is off by default. If you trust the code a little more, IsolatedRuntime(jitless=False) buys the second column and still runs behind the full OS sandbox. Reproduce with benches_py/monty_three_bench.py.

How it works

flowchart LR
    app["Your Python app"] -- "eval, tools" --> parent["IsolatedRuntime<br/>(supervisor)"]
    parent <-->|"validated frames only"| worker
    subgraph worker["Worker process: sandboxed before V8 starts"]
        v8["V8 (jitless)<br/>guest JavaScript"]
    end
    v8 -. "bound functions only" .-> parent
    parent --> tools["Your tools"]

The worker is a separate process with an empty environment, its own session, no privileges, and an OS sandbox applied before the JavaScript engine exists. The parent enforces the deadline, memory and call budgets from outside and treats everything the worker sends as untrusted input.

How it is secure

Defence in depth: each layer assumes the one above it has failed. The threat model is in SECURITY.md and the details in the isolation guide.

What it does not promise. A V8 bug is contained to the worker, not prevented, and about 200 syscalls the engine needs stay reachable. For multi-tenant use, run one runtime per trust unit and put the whole thing in a locked-down container or microVM (see the deployment guidance). Libraries that need WebAssembly, a DOM or a canvas do not work. The engine is only as current as the deno_core release it is built on; a weekly check tells maintainers when a newer V8 becomes available.

Which runtime?

How it was tested

The sandbox is tested the way an attacker would try it: from inside, and against the real kernel.

• Assume-breach syscall sweeps. A sandboxed process fires every syscall in the kernel's table with garbage arguments, from a fresh process each time, and records what is still reachable. Dangerous calls are fired for real (inside a container, never on a host).
• The seccomp program is verified, not trusted. A BPF interpreter in the tests runs the filter's decision logic on any platform, and every syscall number in it is checked against the Linux kernel's own tables (regenerated from a pinned kernel tag by scripts/gen_syscall_tables.py).
• A capability checklist. What untrusted code tries first (read or write a file, reach the network, spawn a process, read the environment; Deno, Node and browser globals; the runtime's own plumbing), through both eval and eval_async, plus a check that nothing reached the host.
• Hostile peers. Fake workers that stop reading, send malformed or oversized frames, flood hash tables or lie about types; fuzzing with Hypothesis; and a port of pydantic/monty's security suite (the cases an in-process runtime cannot survive are pinned as strict expected failures).
• Two codecs, tested against each other. The wire codec is native (Rust) with a readable Python reference; hundreds of tests, including generated frames, require identical results and errors.
• Real libraries, inside the sandbox. pptxgenjs, three.js (GLB export), Vega-Lite and dagre give the same results as an unsandboxed runtime, with their bytes pinned in vendor/libs/; about 25 more (d3, ECharts, jsPDF, Tailwind v4, Prettier, ...) were checked by hand.
• Many kernels. The Linux suite runs on 12 distro images (Debian, Ubuntu, Fedora, AlmaLinux, Amazon Linux; Python 3.10 to 3.14) on both x86_64 and aarch64, and under simulated kernels that lack Landlock, seccomp or both, to prove the sandbox degrades honestly and sandbox="require" fails closed. See .github/workflows/test.yml.
• Zero skips. Platform-specific tests are deselected, never skipped; CI enforces a skip budget of zero so an unrun test cannot hide.
• The worker proves its own confinement. Before any guest code exists it tries to read a file, write one, spawn a process, connect out, signal its parent and (on macOS) read the parent's environment and the machine's hardware ID; a complete sandbox that lets one through refuses to start. Each probe is also checked in reverse: it must report a breach in an unsandboxed process.
• Independent review, and what it found. Three AI reviewers (each given a separate slice of the sandbox and told to reproduce before reporting), GitHub Copilot, and research into how vm2, SandboxJS, isolated-vm and Monty were attacked. The result is a findings table that lists the misses as well as the catches, including a macOS leak of the host's environment, a bridge bug that let a guest abort the process, and a V8 x86_64 startup trap that only a native x86_64 run revealed. Read it in the security report.

Performance

Measured on macOS arm64 (Apple M2) with a release build, on a machine that was not idle, so ranges are shown. Reproduce with benches_py/isolated_report.py and the Criterion and pytest-benchmark suites (BENCHMARKS.md, which also shows 0.5.0 is no slower than 0.4.5).

Jitless V8 (the default for IsolatedRuntime) makes compute-heavy code roughly 1.5 to 2 times slower than with the JIT; jitless=False trades that back for a larger attack surface.

Integrations

• FastMCP tool bridge: expose FastMCP tools to sandboxed JS via bind_function and an in-process fastmcp.Client
• pydantic-ai code mode (JSCodeMode): the JavaScript counterpart of pydantic-ai's Monty-based code mode. The agent gets one run_javascript tool; your other tools become typed tools.* functions the model's code calls with await and Promise.all, with retries, usage limits and approvals mapped onto pydantic-ai's own. Runs offline: examples/pydantic_ai_agent.py. pip install "pydeno[pydantic-ai]"
• Agent sessions (AgentSandbox): state across turns, pause and resume at every tool call (approval flows), a signed replay journal you can dump() and load(), and the tool descriptions and .d.ts for your prompt
• ToolBridge: several Python tools with a total call budget, typed errors the model's JS can branch on, and console.log routed back to Python
• Monty + pydeno: the model's Python runs in Monty, its JavaScript in pydeno, both sandboxed, sharing one tool and one call budget; Python computes, a Vega-Lite chart is drawn in JS
• Vendored npm libraries: run real npm document-generation libraries (pptxgenjs, pdf-lib) from their browser bundles inside the sandbox; see the guide
• Arrow IPC dataframes: move 100k+ row tables into the sandbox as Arrow IPC bytes instead of JSON objects (5 ms vs 253 ms); see the guide

Documentation

• Security policy and threat model · the isolation guide
• Quick Start · Concepts · Guides · Use cases · API reference
• Agent skill: an Agent Skills SKILL.md that teaches coding agents (Claude Code and others) to use pydeno correctly. Copy skills/pydeno/ into your agent's skills directory, e.g. .claude/skills/
• Benchmarks · Changelog

Status and contributing

pydeno is experimental: expect breaking changes between versions. Found a way out of the sandbox? Please report it privately, as described in SECURITY.md. Everything else: issues and pull requests are welcome; start with docs/contributing/.

Licensed under the MIT License.

Acknowledgements

pydeno began as a fork of jsrun by Xin Fu, which had the original idea of a Python library that runs JavaScript on a Rust runtime built on deno_core. We took that idea and its foundations, then changed a great deal: the sandboxed worker process and OS confinement, the tool boundary, the wire codec, the resource limits, and most of the tests are new. Thank you to jsrun for the starting point. The MIT licence and original copyright are kept, and docs/contributing/upstream-divergence.md records what came from where.

Thanks also to Monty by Pydantic, whose design for running agent-written code (limits, host functions, a public challenge to break it) shaped how we think about this problem; the two sandboxes work well side by side.