Skip to main content
Get Started
Getting Started

Crash Course

A fast tour of Secure Exec: install, run code, capture output, and the core SDK concepts.

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

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.

Read more about Output Capture.

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

Read more about Executing Code.

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

Read more about Resource Limits.

Where to go next

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

Edit this page