Getting Started

Crash Course

This is a fast, guided walk through the essentials: install the SDK, boot a runtime, run guest code, and capture its output. By the end you will understand the core loop and know where to go for more.

NodeRuntime is the entry point: it boots a virtualized VM and runs guest JavaScript end to end, secure by default (no host filesystem, network, or process access until you allow it) and with every create() option optional so you can start with zero setup.

For exact signatures and option shapes, see the TypeScript SDK reference.

Install

npm install secure-exec

bun add secure-exec

pnpm add secure-exec

yarn add secure-exec

Your first run

The core loop is always the same: create a runtime, run code, dispose it.

import { NodeRuntime } from "secure-exec";

const rt = await NodeRuntime.create();
try {
  const { stdout } = await rt.exec("console.log('hi', 1 + 1)");
  console.log(stdout); // "hi 2\n"
} finally {
  await rt.dispose();
}

NodeRuntime.create(): boots a fresh VM. Reuse one runtime across many runs.
rt.exec(code): runs guest code as an ES module.
rt.dispose(): releases the VM and its sidecar. Always call it when done.

See Full Example

Capture output

exec() returns the streams and exit code from the run.

const { stdout, stderr, exitCode } = await rt.exec(`
  console.log("to stdout");
  console.error("to stderr");
`);
console.log(exitCode); // 0

exitCode is 0 on a clean exit and non-zero if the guest threw or was killed.

Return a value

Use run<T>() when you want a typed value back instead of parsing stdout. The guest returns it with globalThis.__return(value).

const { value } = await rt.run<{ sum: number }>(`
  globalThis.__return({ sum: 2 + 40 });
`);
console.log(value?.sum); // 42

Set a timeout

Pass a timeout so a runaway guest cannot run forever. The VM kills the process when the budget elapses.

const result = await rt.exec(`while (true) {}`, { timeout: 1000 });
console.log(result.exitCode); // non-zero: the guest was killed

Where to go next

You now know the core loop. Each feature builds on it:

Executing Code: exec, run, modules, and inputs.
Child Processes: spawn() for long-running guest programs.
Resident Runner: keep a guest process alive for fast repeated runs.
Filesystem: read, write, and seed the virtualized VFS.
NPM & Module Loading: resolve real npm packages inside the VM.
Networking: guest fetch, sockets, and driving HTTP into a guest server.
Bindings: expose curated host functions to guest code.
Permissions: grant network and other access over the secure default.
Runtime & Platform: shape the env, cwd, and platform the guest sees.
TypeScript: compile and type-check inside the sandbox.