@suaveplan/sandbox - Server-tier sandboxed code execution: node:vm, node:worker_threads, and node:child_process engines, pre-warmed pool, audit logger, sliding-window rate limiter, pattern-based code transformer, async result streamer.

Server-tier sandboxed code execution for @suaveplan plugin hosts and agent runtimes. Ships four SandboxEngine implementations (a node:vm default, real node:worker_threads for OS-thread isolation, real node:child_process for process isolation, and a structural isolated-vm adapter), a pre-warmed SandboxPool, an async ResultStreamer, a pattern-based CodeTransformer, an allowlist-based ModuleResolver, a sliding-window ResourceLimiter, and a SHA-256 AuditLogger — all behind a createSandbox() facade with Zod-validated config and full OpenTelemetry instrumentation.

Documentation tree

audit-logger — AuditLogger records every sandbox execution with a structured AuditLogEntry. Each entry carries an ISO-8601 timesta…
- audit-logger — AuditLogger records every sandbox execution with a structured AuditLogEntry. Each entry carries an ISO-8601 timesta…
code-transformer — CodeTransformer is a defence-in-depth layer that pattern-matches dangerous code constructs before they reach the engi…
- code-transformer — CodeTransformer is a defence-in-depth layer that pattern-matches dangerous code constructs before they reach the engi…
error-codes — @suaveplan/sandbox raises typed SandboxError instances rather than plain Error so consumers can discriminate fail…
- error-codes — @suaveplan/sandbox raises typed SandboxError instances rather than plain Error so consumers can discriminate fail…
isolate-engine — IsolateEngine implements the SandboxEngine contract over a structural IsolateFactory interface that mirrors the `…
- isolate-engine — IsolateEngine implements the SandboxEngine contract over a structural IsolateFactory interface that mirrors the `…
module-resolver — ModuleResolver is the gatekeeper between user code and the host's module surface. It maintains an allowlist of module…
- module-resolver — ModuleResolver is the gatekeeper between user code and the host's module surface. It maintains an allowlist of module…
pool — SandboxPool amortises engine startup cost across many short executions by maintaining a warm pool of SandboxEngine…
- pool — SandboxPool amortises engine startup cost across many short executions by maintaining a warm pool of SandboxEngine…
resource-limiter — ResourceLimiter enforces two complementary controls on the sandbox boundary: a sliding-window rate limit (so a single…
- resource-limiter — ResourceLimiter enforces two complementary controls on the sandbox boundary: a sliding-window rate limit (so a single…
result-streamer — ResultStreamer delivers sandbox output incrementally rather than as a single end-of-execution dump. The most common u…
- result-streamer — ResultStreamer delivers sandbox output incrementally rather than as a single end-of-execution dump. The most common u…
sandbox — createSandbox is the public entry point of the package. It composes the engine, ModuleResolver, ResourceLimiter,…
- sandbox — createSandbox is the public entry point of the package. It composes the engine, ModuleResolver, ResourceLimiter,…
schemas — Zod schemas guard every public boundary of @suaveplan/sandbox. The package never trusts its caller; instead, every ar…
- schemas — Zod schemas guard every public boundary of @suaveplan/sandbox. The package never trusts its caller; instead, every ar…
spawn-engine — SpawnEngine uses node:child_process.spawn for the strongest isolation the package offers: a fresh OS process spawne…
- runner — runner.ts is the child-process entry point invoked by SpawnEngine. The parent process spawns it via `node:child_pro…
- spawn-engine — SpawnEngine uses node:child_process.spawn for the strongest isolation the package offers: a fresh OS process spawne…
telemetry — @suaveplan/sandbox ships first-class OpenTelemetry instrumentation so consumers running the sandbox at any scale can…
- telemetry — @suaveplan/sandbox ships first-class OpenTelemetry instrumentation so consumers running the sandbox at any scale can…
vm-engine — VmEngine is the default sandbox engine. It uses node:vm directly: caller code is compiled with new vm.Script(...)…
- vm-engine — VmEngine is the default sandbox engine. It uses node:vm directly: caller code is compiled with new vm.Script(...)…
worker-engine — WorkerEngine uses real node:worker_threads for true OS-thread isolation. Each execute call spawns a fresh `Worker…
- worker-engine — WorkerEngine uses real node:worker_threads for true OS-thread isolation. Each execute call spawns a fresh `Worker…

Install

bun add @suaveplan/sandbox

Quick start

import { createSandbox } from "@suaveplan/sandbox";

const sandbox = createSandbox({ timeout: 5000, engine: "vm" });
const result = await sandbox.execute("2 + 3");
console.log(result.result); // 5
sandbox.destroy();

Engine selection

Engine	Boundary	Use when
`vm` (default)	`node:vm` context	Trusted accident-isolation, fastest path.
`worker`	`node:worker_threads`	Adversarial code, OS-thread isolation.
`spawn`	`node:child_process`	Adversarial code, full process isolation.
`isolate`	`isolated-vm` (optional dep)	Strongest in-process isolation.

Wire engine: "isolate" with a customEngine factory that constructs a real IsolateEngine over your installed isolated-vm peer dependency.

Modules

Co-located docs for every public surface:

error-codes — SANDBOX_CODES, SandboxError.
schemas — Zod boundaries.
telemetry — OTel instruments + recorders.
audit-logger — execution audit log.
resource-limiter — rate-limit + output truncation.
module-resolver — denylist/allowlist + builtins.
code-transformer — regex-based dangerous-pattern guard.
vm-engine — default engine.
worker-engine — OS-thread engine.
spawn-engine — process engine.
runner — spawn-engine child entry point.
isolate-engine — isolated-vm structural adapter.
pool — pre-warmed engine pool.
result-streamer — async streaming output.
sandbox — createSandbox facade.

Security model

vm-engine shares the host realm and is NOT a security boundary against adversarial code — vm.runInContext can be escaped via prototype-chain tricks. For adversarial isolation, use worker-engine or spawn-engine, both of which sit behind real OS-level boundaries. The code-transformer is a defence-in-depth layer that catches the obvious accidents (process.exit, require, eval, etc.); it is not a substitute for an engine-level boundary.

Tier

Server (node:vm / node:worker_threads / node:child_process / node:crypto). Targets Node ≥ 20 (and Bun, which provides the same APIs).