isolated-vm

isolated-vm is a native Node.js addon that exposes V8’s Isolate interface directly, letting you create JavaScript execution contexts that are completely isolated from each other and from the host Node process — free of require, filesystem access, or any other capability the host runtime normally grants.

This makes it a building block for running untrusted or third-party JavaScript safely: plugin systems, user-submitted scripts, or multi-tenant code execution, where you need real sandboxing guarantees rather than the weaker isolation Node’s built-in vm module provides. The project is explicitly in maintenance mode, with an experimental rewrite in progress on a separate branch.

What You Get

• Native bindings to V8’s Isolate API for creating fully separate JavaScript heaps within one Node process
• Explicit, opt-in bridging of values and references between isolates via Reference and transferable objects
• CPU and memory limits enforceable per isolate, with the ability to dispose an isolate and reclaim its resources
• Compatibility matrix tying isolated-vm major versions to specific Node.js major versions (since V8’s ABI changes across Node releases)
• A CPU profiler and inspector integration (inspector-example.js) for debugging isolate code

Common Use Cases

• Running third-party or user-submitted JavaScript plugins inside a host application without giving them Node API access
• Multi-tenant code execution platforms that need per-tenant CPU/memory limits and hard isolation
• Serverless-style function runners that need to spin up and tear down fresh JS contexts quickly
• Sandboxing template or scripting logic (e.g. user-defined formulas or automations) inside a larger app

Under The Hood

Architecture - the addon is organized around src/isolate (isolate lifecycle: creation, disposal, limits) and src/external_copy (the serialization/copy layer that moves values across the isolate boundary since isolates share no memory by default), with src/module wiring the native bindings into the JS-facing isolated-vm.js/isolated-vm.d.ts entry points; a native-example directory demonstrates embedding native addons inside a sandboxed isolate. Tech Stack - primarily C++ against V8’s embedder API, glued to Node via node-gyp/node-gyp-build with prebuilt binaries fetched per Node ABI version (hence the strict Node-version-to-isolated-vm-version compatibility table in the README), with a thin JS/TypeScript wrapper layer on top. Code Quality - the tests/ directory is unusually large and adversarial for a native addon, covering deadlocks, dispose races, catastrophic errors, context leaks, and cross-context instance edge cases — reflecting the project’s core promise of hard isolation guarantees; linting is done via clang-tidy over the C++ sources rather than a JS linter, appropriate for a mostly-native codebase. API Design - the library requires deliberate, explicit marshaling of every value crossing the isolate boundary (via Reference, Copy, Transferable), which is more verbose than Node’s built-in vm module but is exactly the tradeoff that provides real security isolation rather than the shared-heap illusion of isolation vm gives.