Class: SandboxEngine

Defined in: packages/core/src/sandbox/SandboxEngine.ts:190

Zero-trust V8 sandbox for executing LLM-provided JavaScript.

Creates a single V8 Isolate at construction time and reuses it across all execute() calls. Each call gets a fresh, empty Context with no dangerous globals (no process, require, fs, etc.).

If the isolate dies (e.g., OOM), it is automatically recreated on the next execute() call.

Example

const sandbox = new SandboxEngine({ timeout: 3000, memoryLimit: 64 });

const result = await sandbox.execute(
    '(data) => data.filter(d => d.risk > 90)',
    [{ name: 'A', risk: 95 }, { name: 'B', risk: 30 }],
);

if (result.ok) {
    console.log(result.value); // [{ name: 'A', risk: 95 }]
}

// IMPORTANT: dispose when no longer needed
sandbox.dispose();

Constructors

Constructor

new SandboxEngine(config?): SandboxEngine;

Defined in: packages/core/src/sandbox/SandboxEngine.ts:199

Parameters

Parameter	Type
config?	SandboxConfig

Returns

SandboxEngine

Accessors

isDisposed

Get Signature

get isDisposed(): boolean;

Defined in: packages/core/src/sandbox/SandboxEngine.ts:393

Check if the engine has been disposed.

Returns

boolean

Methods

dispose()

dispose(): void;

Defined in: packages/core/src/sandbox/SandboxEngine.ts:380

Release all resources held by this engine.

After calling dispose(), any subsequent execute() calls will return { ok: false, code: 'UNAVAILABLE' }.

Returns

void

---

execute()

execute<T>(
   code, 
   data, 
options?): Promise<SandboxResult<T>>;

Defined in: packages/core/src/sandbox/SandboxEngine.ts:250

Execute a JavaScript function string against the provided data.

The function is compiled and run in a sealed V8 isolate with:

• No process, require, fs, or network access
• Strict timeout enforcement (async, non-blocking)
• Memory limit enforcement
• Automatic C++ pointer cleanup (ExternalCopy, Script, Context)
• Cooperative cancellation via AbortSignal (Connection Watchdog)

Type Parameters

Type Parameter	Default type
T	unknown

Parameters

Parameter	Type	Description
code	string	A JavaScript function expression as a string. Must be an arrow function or function expression. Example: (data) => data.filter(d => d.value > 10)
data	unknown	The data to pass into the function. Deeply copied into the isolate (no references leak).
options?	{ signal?: AbortSignal; }	Optional execution options.
options.signal?	AbortSignal	AbortSignal for cooperative cancellation. When the signal fires (e.g., MCP client disconnects), the engine calls isolate.dispose() to kill the V8 C++ threads instantly. The isolate is auto-recovered on the next .execute() call.

Returns

Promise<SandboxResult<T>>

A SandboxResult with the computed value or an error.

---

telemetry()

telemetry(sink): this;

Defined in: packages/core/src/sandbox/SandboxEngine.ts:220

Set the telemetry sink for sandbox.exec event emission. When set, every execute() call emits a telemetry event visible in the Inspector TUI.

Parameters

Parameter	Type
sink	TelemetrySink

Returns

this