isolated-vm

@execbox/isolated-vm

isolated-vm executor backend for @execbox/core.

Docs: https://execbox.aallam.com

Choose isolated-vm When

• you explicitly want the isolated-vm runtime instead of QuickJS
• your environment can support the native addon install
• you are prepared to run Node 22+ with --no-node-snapshot

If you want the simpler default backend, use @execbox/quickjs instead.

Examples

• Basic provider execution on isolated-vm
• QuickJS-based execbox examples for the shared API surface
• Worker-hosted QuickJS example for the alternate host mode
• Full examples index

Install

npm install @execbox/core @execbox/isolated-vm

Requirements

• Node 22+ must run with --no-node-snapshot
• the optional isolated-vm native dependency must install successfully in the host environment
• native-addon failures are surfaced when IsolatedVmExecutor is constructed or used
• advanced consumers can import the reusable runner from @execbox/isolated-vm/runner

Security Notes

• Each execution gets a fresh isolated-vm context with JSON-only tool and result boundaries.
• In the default deployment model, provider definitions are controlled by the host application, while hostile users control guest code and tool inputs.
• This package is still in-process execution. It is not a substitute for a separate trust boundary such as a container or VM.
• Providers remain the real capability boundary. If a tool is dangerous, guest code can invoke it.

Architecture Docs

• Execbox architecture overview
• Execbox executors
• Execbox MCP adapters and protocol

Usage

import { resolveProvider } from "@execbox/core";
import { IsolatedVmExecutor } from "@execbox/isolated-vm";

const provider = resolveProvider({
  tools: {
    echo: {
      execute: async (input) => input,
    },
  },
});

const executor = new IsolatedVmExecutor();
const result = await executor.execute("await codemode.echo({ ok: true })", [
  provider,
]);

This package is verified through the workspace security flows:

npm run test:security
npm run test:isolated-vm
npm run verify:isolated-vm

The required CI lane runs the isolated-vm suite on Node 24 with --no-node-snapshot, which is the best local environment to match when validating native-runtime changes.

If process stability and trust separation matter more than in-process performance, prefer @execbox/quickjs with host: "process" or a remote transport boundary.