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.

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.

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" agent: the model submits one JS batch script instead of many separate tool calls, run safely with a timeout
• 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.