skills/plugins/document-navigator/docs/devtools/tooling/sandbox/README.md

@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).