Getting Started

Quickstart

Get Secure Exec running in a few minutes.

Install

Create a runtime

NodeRuntime.create() boots a fully virtualized VM behind the native sidecar. Guest code runs inside the kernel isolation boundary with no host escapes. All options are optional: cwd defaults to /workspace, and permissions default to a secure policy that denies network access (see step 4).
import { NodeRuntime } from "secure-exec"; const runtime = await NodeRuntime.create();

Run code

Use run() when you want a JSON value back; the guest calls globalThis.__return(value) to set it. Use exec() when you care about side effects and want to capture stdout/stderr/exitCode. Guest code runs as an ES module, so import and top-level await both work.

import { NodeRuntime } from "secure-exec";

// Boot a fully virtualized runtime. Guest code runs inside the kernel
// isolation boundary - no host escapes.
const runtime = await NodeRuntime.create();

try {
	// run() executes guest JavaScript as an ES module and returns the value the
	// guest passes to globalThis.__return(). stdout/stderr are captured too.
	const result = await runtime.run<{ message: string; sum: number }>(`
		console.log("hello from secure-exec");
		__return({ message: "hello from secure-exec", sum: 1 + 2 });
	`);

	console.log("stdout:", JSON.stringify(result.stdout.trim()));
	console.log("value:", result.value);
	console.log("exitCode:", result.exitCode);
} finally {
	// Tear down the VM and release the sidecar.
	await runtime.dispose();
}

import { NodeRuntime } from "secure-exec";

const runtime = await NodeRuntime.create();

try {
  // exec() runs guest code for its side effects and captures the streams.
  const result = await runtime.exec(`
    console.log("hello from secure-exec");
    console.error("this goes to stderr");
  `);

  console.log("stdout:", JSON.stringify(result.stdout.trim()));
  console.log("stderr:", JSON.stringify(result.stderr.trim()));
  console.log("exitCode:", result.exitCode);
} finally {
  await runtime.dispose();
}

See Full Example

Configure permissions (optional)

Guest code is deny-by-default for network access. Pass a permissions policy to NodeRuntime.create() to opt in; it merges over the secure default, so you only specify what you want to change:
const runtime = await NodeRuntime.create({ permissions: { network: "allow" }, });
See Permissions for the full scope list and merge semantics.

Quickstart

Next steps

Crash Course

Permissions