Secure Exec

https://secureexec.dev/docs
Admin
Secure Exec is a TypeScript SDK that executes JavaScript in isolated V8 sandboxes with configurable...
Tokens:22,913
Snippets:263
Trust Score:5.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example execution output

Source: https://secureexec.dev/docs/use-cases/ai-agent-code-exec

Shows the expected console output when running the provided sandboxed JavaScript example.

```text
exitCode: 0
stdout: computed 20 fibonacci numbers
returned value: {"fibonacci":[0,1,1,2,3,5,8,13,21,34,55,89,144,233,377,610,987,1597,2584,4181],"sum":10945}

escape attempt exitCode: 0
escape attempt stdout: guest hostname: secure-exec
```

--------------------------------

### Example execution output

Source: https://secureexec.dev/docs/features/module-loading

The expected output from the virtualized execution snippet.

```text
exitCode: 0
guest stdout:
resolved node:path via import -> /workspace/data/report.txt
resolved node:os via require -> linux
{"basename":"report.txt","joined":"/workspace/data/report.txt","platform":"linux"}
```

--------------------------------

### Install Secure Exec SDK

Source: https://secureexec.dev/docs/crash-course

Commands to install the secure-exec package using various package managers.

```bash
npm install secure-exec
```

```bash
bun add secure-exec
```

```bash
pnpm add secure-exec
```

```bash
yarn add secure-exec
```

--------------------------------

### Install secure-exec-client via Cargo

Source: https://secureexec.dev/docs/sdks/rust

Use the cargo add command to include the crate in your project.

```bash
cargo add secure-exec-client
```

--------------------------------

### Server execution output

Source: https://secureexec.dev/docs/use-cases/dev-servers

Expected console output when running the server example.

```text
spawned guest server, pid: 1000000
server listening on 127.0.0.1:3000
health check -> 200 "{\"ok\":true}"
GET / -> 200 "hello from the sandboxed dev server"
RESULT {"status":200,"body":"hello from the sandboxed dev server"}
server stopped
```

--------------------------------

### Initialize Secure Exec Runtime

Source: https://secureexec.dev/docs/comparison/isolated-vm

Demonstrates creating a Secure Exec runtime with default security settings and an example of enabling network permissions.

```typescript
import { NodeRuntime } from "secure-exec";

// Deny-by-default: no network, filesystem and processes are virtualized.
const rt = await NodeRuntime.create();

// Opt into network egress; it is still mediated by the kernel socket table.
const networked = await NodeRuntime.create({
  permissions: { network: "allow" },
});
```

--------------------------------

### Install @secure-exec/typescript

Source: https://secureexec.dev/docs/features/typescript

Install the required packages via npm.

```bash
npm install @secure-exec/typescript secure-exec
```

--------------------------------

### Run Cold Start Matrix

Source: https://secureexec.dev/docs/benchmarks

Executes the cold start benchmark matrix and redirects output to files.

```bash
SECURE_EXEC_SIDECAR_BIN="$PWD/target/release/secure-exec-sidecar" \
  pnpm --silent --dir packages/benchmarks bench:coldstart \
  > packages/benchmarks/results/coldstart-local.json \
  2> packages/benchmarks/results/coldstart-local.log
```

--------------------------------

### Install the Secure Exec SDK

Source: https://secureexec.dev/docs/sdks/typescript

Use npm to add the secure-exec package to your project dependencies.

```bash
npm install secure-exec
```

--------------------------------

### Example probe output

Source: https://secureexec.dev/docs/features/runtime-platform

The structured JSON output returned by the guest probe execution.

```json
{
  platform: 'linux',
  hasProcess: true,
  hasBuffer: true,
  nodeVersion: '22.0.0',
  sha256: 'fa7ce60dac0cc1bfe7424a68e47ad3d712345cf936431bb147cd5f5de0371a4a',
  joinedPath: '/home/agentos/report.txt'
}
```

--------------------------------

### Spawn and drive requests to a sandboxed server

Source: https://secureexec.dev/docs/use-cases/dev-servers

Demonstrates booting a node:http server inside a secure isolate and using fetch to drive requests into it. Requires network permissions to be enabled in the runtime configuration.

```typescript
import { NodeRuntime } from "secure-exec";

// A user's "dev server": untrusted, long-running server-style code. It boots a
// real node:http server and keeps serving until it is killed, all inside the
// secure-exec VM with no access to the host machine.
const devServer = `
import http from "node:http";

// Start the user's server, exactly as they wrote it.
const app = http.createServer((req, res) => {
  if (req.url === "/health") {
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify({ ok: true }));
    return;
  }
  res.writeHead(200, { "content-type": "text/plain" });
  res.end("hello from the sandboxed dev server");
});

// Listen on loopback inside the VM. The kernel owns this socket; it never
// touches a real host port. The process stays alive serving requests until the
// host kills it.
app.listen(3000, "127.0.0.1", () => {
  console.log("server listening on 127.0.0.1:3000");
});
`;

// The guest binds a loopback port, so opt in to networking. NodeRuntime.create()
// denies network by default; permissions merge over that secure default.
const runtime = await NodeRuntime.create({ permissions: { network: "allow" } });

try {
	// spawn() starts the server as a long-running guest process and returns a
	// handle immediately, without waiting for it to exit.
	const server = await runtime.spawn(devServer, {
		onStdout: (chunk) => process.stdout.write(new TextDecoder().decode(chunk)),
	});
	console.log("spawned guest server, pid:", server.pid);

	try {
		// Block until the guest is actually accepting connections on the port,
		// then drive requests into it.
		await runtime.waitForListener({ port: 3000 });

		// Drive a real host->guest request into the running server.
		const health = await runtime.fetch(3000, { path: "/health" });
		console.log("health check ->", health.status, JSON.stringify(health.body));

		const res = await runtime.fetch(3000, { method: "GET", path: "/" });
		console.log("GET / ->", res.status, JSON.stringify(res.body));

		console.log(
			"RESULT " + JSON.stringify({ status: res.status, body: res.body }),
		);
	} finally {
		// Tear the server down and wait for the guest process to exit.
		server.kill();
		await server.wait();
		console.log("server stopped");
	}
} finally {
	// Tear down the VM and release the sidecar.
	await runtime.dispose();
}
```

--------------------------------

### Seeding files in the VM

Source: https://secureexec.dev/docs/features/module-loading

Demonstrates how to write files to the VM filesystem during initialization or at runtime using the NodeRuntime API.

```javascript
// At boot.
const rt = await NodeRuntime.create({
  files: { "/tmp/node_modules/greet/index.js": "module.exports = () => 'hi';" },
});

// Or after boot.
await rt.writeFile("/tmp/node_modules/greet/package.json", '{"main":"index.js"}');
const bytes = await rt.readFile("/tmp/node_modules/greet/index.js");
```

--------------------------------

### Create a NodeRuntime

Source: https://secureexec.dev/docs/quickstart

Initializes a fully virtualized VM instance for guest code execution.

```typescript
import { NodeRuntime } from "secure-exec";

const runtime = await NodeRuntime.create();
```

--------------------------------

### Expected Output for TypeScript Sandbox Execution

Source: https://secureexec.dev/docs/features/typescript

The console output resulting from the compilation and type-checking example.

```text
Compiled TypeScript to JavaScript inside the sandbox.
exitCode: 0
guest stdout:
hello secure-exec #1
hello secure-exec #2
hello secure-exec #3
type check success: false
  error TS2322 (line 1): Type 'string' is not assignable to type 'number'.
OK: TypeScript compiled and type-checked inside the sandbox.
```

--------------------------------

### Configure Runtime Permissions

Source: https://secureexec.dev/docs/comparison/cloudflare-workers

Demonstrates creating a Secure Exec runtime with default restrictions and opting into network access.

```typescript
import { NodeRuntime } from "secure-exec";

// Default: no network access. Filesystem and processes are virtualized.
const sandboxed = await NodeRuntime.create();

// Opt into network access while keeping the other defaults.
const networked = await NodeRuntime.create({
  permissions: { network: "allow" },
});
```

--------------------------------

### Execute Guest JavaScript

Source: https://secureexec.dev/docs/sdks/typescript

Initialize the NodeRuntime, execute code within the VM, and ensure resources are cleaned up using the dispose method.

```typescript
import { NodeRuntime } from "secure-exec";

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

--------------------------------

### Generate LLM-authored code with chained bindings

Source: https://secureexec.dev/docs/use-cases/code-mode

Example of code generated by an LLM that uses callBinding to interact with host handlers and returns a structured result.

```javascript
// Imagine this string was written by the LLM. It chains three host binding calls
// with real control flow (Promise.all, arithmetic, branching) in one execution,
// then hands a single structured result back to the host. callBinding resolves
// with the host handler's return value.
const llmGeneratedCode = `
const [sf, tokyo] = await Promise.all([
  callBinding("get-weather", { city: "San Francisco" }),
  callBinding("get-weather", { city: "Tokyo" }),
]);

const diffF = Math.abs(sf.temp_f - tokyo.temp_f);
const diffC = await callBinding("calculate", { expression: `${diffF} * 5 / 9` });

console.log("chained 3 binding calls in one sandbox execution");

globalThis.__return({
  san_francisco: sf,
  tokyo: tokyo,
  difference: { fahrenheit: diffF, celsius: diffC.result },
  warmer: sf.temp_f > tokyo.temp_f ? "San Francisco" : "Tokyo",
});
`;
```

--------------------------------

### Spawn Guest Child Processes

Source: https://secureexec.dev/docs/features/child-processes

Demonstrates using node:child_process within a virtualized VM to execute shell commands and Node.js processes.

```javascript
import { NodeRuntime } from "secure-exec";

// Boot a fully virtualized VM. The guest runs inside the kernel isolation
// boundary, and any child processes it spawns are themselves kernel-managed
// processes - they never spawn real host processes.
const rt = await NodeRuntime.create();

try {
  // Guest code runs as an ES module inside the VM. It uses the standard
  // node:child_process module to spawn a command available in the VM and read
  // its output. Here we spawn `sh -c` to echo a message, and `node` to report
  // its own version - both run as kernel-managed child processes.
  const { stdout, stderr, exitCode } = await rt.exec(`
    import { execFileSync } from "node:child_process";

    // Spawn a shell command and capture its stdout.
    const shellOut = execFileSync("sh", ["-c", "echo hello from a child process"], {
      encoding: "utf8",
    });
    console.log("sh output:", shellOut.trim());

    // Spawn node as a child process and read its version.
    const nodeVersion = execFileSync("node", ["--version"], {
      encoding: "utf8",
    });
    console.log("child node version:", nodeVersion.trim());
  `);

  console.log("exitCode:", exitCode);
  if (stderr.trim()) console.log("guest stderr:", stderr.trim());
  console.log("guest stdout:");
  console.log(stdout.trim());
} finally {
  await rt.dispose();
}
```

--------------------------------

### Configure sandbox permissions

Source: https://secureexec.dev/docs/use-cases/ai-agent-code-exec

Demonstrates how to override default sandbox permissions, such as enabling network access.

```javascript
import { NodeRuntime } from "secure-exec";

// network is already denied by default; this opts it back in while the other
// scopes keep their defaults.
const rt = await NodeRuntime.create({
  permissions: { network: "allow" },
});
```

--------------------------------

### Booting a Secure Exec runtime

Source: https://secureexec.dev/docs/comparison/sandbox

Initializes a NodeRuntime instance to execute code in a virtualized VM with default network restrictions.

```typescript
import { NodeRuntime } from "secure-exec";

// Network is denied by default; the guest runs in its own virtualized VM.
const rt = await NodeRuntime.create();
try {
  const result = await rt.run<number>(`
    __return(40 + 2);
  `);
  console.log(result.value); // 42
} finally {
  await rt.dispose();
}
```

--------------------------------

### Run code and capture output with exec()

Source: https://secureexec.dev/docs/features/executing-code

Executes guest code and returns an object containing stdout, stderr, and the exit code.

```javascript
import { NodeRuntime } from "secure-exec";

const rt = await NodeRuntime.create();
const { stdout, exitCode } = await rt.exec(`
  import os from "node:os";
  console.log("platform:", os.platform());
`);
console.log(stdout, exitCode);
await rt.dispose();
```

--------------------------------

### Run Benchmark Suite

Source: https://secureexec.dev/docs/benchmarks

Executes the full suite of performance benchmarks.

```bash
pnpm --dir packages/benchmarks bench
```

--------------------------------

### NodeRuntime.create({ tools })

Source: https://secureexec.dev/docs/features/bindings

Registers a set of tools during the initialization of the NodeRuntime. Each tool is defined by a description, an input schema, and a handler function that executes on the host.

```APIDOC
## NodeRuntime.create({ tools })

### Description
Initializes a new NodeRuntime instance with a curated set of host-backed capabilities (tools) that the guest can invoke.

### Parameters
- **tools** (Object) - Required - A map where keys are tool names and values are tool definitions.
  - **description** (string) - Required - A description of the tool's purpose.
  - **inputSchema** (Object) - Required - A JSON schema defining the expected input parameters.
  - **handler** (Function) - Required - The host-side function executed when the tool is called by the guest.
```

--------------------------------

### Compile and Type-check a TypeScript Project

Source: https://secureexec.dev/docs/features/typescript

Demonstrates initializing a TypeScript project with a tsconfig.json and source files, then performing compilation or type-checking.

```typescript
import { createTypeScriptTools } from "@secure-exec/typescript";

const tools = createTypeScriptTools({
  files: {
    "/root/tsconfig.json": JSON.stringify({
      compilerOptions: { strict: true, target: "ES2022", module: "ESNext" },
      include: ["src"],
    }),
    "/root/src/index.ts": "export const answer: number = 42;\n",
  },
});

// Compile every file the tsconfig includes, emitting into the VM filesystem.
const compiled = await tools.compileProject({ cwd: "/root" });
console.log("project compiled:", compiled.success);
console.log("emitted:", compiled.emittedFiles);

// Or type-check only, without emitting any output.
const checked = await tools.typecheckProject({ cwd: "/root" });
console.log("project type-checks:", checked.success);
```

--------------------------------

### Drive HTTP requests into a guest server

Source: https://secureexec.dev/docs/comparison/cloudflare-workers

Demonstrates spawning a guest HTTP server and using rt.fetch to communicate with it from the host.

```javascript
import { NodeRuntime } from "secure-exec";

const rt = await NodeRuntime.create();
try {
  // Start a long-running guest HTTP server and get a live handle back.
  const server = await rt.spawn(`
    import http from "node:http";
    http.createServer((_req, res) => res.end("ok")).listen(3000);
  `);

  // Block until the listener is up, then drive a request into it from the host.
  await rt.waitForListener({ port: 3000 });
  const res = await rt.fetch(3000, { path: "/" });
  console.log(res.status, res.body); // 200 ok

  server.kill();
  await server.wait();
} finally {
  await rt.dispose();
}
```

--------------------------------

### Registering tools at boot with NodeRuntime

Source: https://secureexec.dev/docs/features/bindings

Define tools during runtime initialization by passing a tools object to NodeRuntime.create().

```typescript
import { NodeRuntime } from "secure-exec";

const rt = await NodeRuntime.create({
  tools: {
    "get-weather": {
      description: "Look up the current temperature for a city",
      inputSchema: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
      },
      // Runs on the HOST. The return value is delivered back to the guest.
      handler: ({ city }: { city: string }) => {
        const table: Record<string, { temp_f: number }> = {
          "San Francisco": { temp_f: 61 },
          Tokyo: { temp_f: 75 },
        };
        return table[city] ?? { temp_f: null };
      },
    },
  },
});
```

--------------------------------

### Seed the host environment with NodeRuntime.create

Source: https://secureexec.dev/docs/features/runtime-platform

Configures the guest environment, including environment variables, virtual file system seeding, directory mounts, permissions, and custom host-side tools.

```typescript
const rt = await NodeRuntime.create({
	env: { API_BASE: "https://example.test" },   // guest process env
	cwd: "/workspace",                            // default working dir
	files: { "/root/data.json": '{"ok":true}' },  // seed VFS bytes
	mounts: [                                      // project host dirs, Docker-style, lazy
		{ guestPath: "/root/node_modules/typescript", hostPath: "/abs/typescript", readOnly: true },
	],
	permissions: { network: "allow" },            // merged over secure default (network denied)
	tools: {                                       // host capabilities the guest calls as commands
		add: {
			description: "Add two numbers",
			inputSchema: { type: "object", properties: { a: { type: "number" }, b: { type: "number" } }, required: ["a", "b"] },
			handler: ({ a, b }: { a: number; b: number }) => ({ sum: a + b }),
		},
	},
	loopbackExemptPorts: [3000],                   // let non-loopback connections reach this port
	commandsDir: "/abs/wasm/commands",             // override the WASM `sh`/coreutils dir
});
```

--------------------------------

### run<T>(code: string, options?: RunOptions)

Source: https://secureexec.dev/docs/features/executing-code

Executes guest code and returns a JSON-serializable value passed back from the guest via globalThis.__return().

```APIDOC
## run<T>(code, options)

### Description
Executes guest code and decodes a value returned by the guest using the injected globalThis.__return(value) function.

### Parameters
- **code** (string) - Required - The JavaScript code to execute.
- **options** (RunOptions) - Optional - Configuration including stdin, env, cwd, timeout, AbortSignal, onStdout, and onStderr.
```

--------------------------------

### Execute Code in a Runtime

Source: https://secureexec.dev/docs/crash-course

Demonstrates the core lifecycle of creating a runtime, executing code, and disposing of the VM.

```typescript
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();
}
```

--------------------------------

### Interact with the live runtime after boot

Source: https://secureexec.dev/docs/features/runtime-platform

Performs post-boot operations such as writing files, reading files, and registering additional tools dynamically.

```typescript
await rt.writeFile("/root/late.json", '{"added":"after boot"}');
const bytes = await rt.readFile("/root/late.json"); // Uint8Array
await rt.registerTools({
	now: { description: "epoch ms", inputSchema: { type: "object" }, handler: () => Date.now() },
});
```

--------------------------------

### Execute code with Secure Exec

Source: https://secureexec.dev/docs/comparison/isolated-vm

Demonstrates initializing a NodeRuntime and executing code within the virtualized environment.

```typescript
import { NodeRuntime } from "secure-exec";

const rt = await NodeRuntime.create();
try {
  const result = await rt.run<number>(`
    __return(40 + 2);
  `);
  console.log(result.value); // 42
} finally {
  await rt.dispose();
}
```

--------------------------------

### Register and Invoke Curated Host Tools

Source: https://secureexec.dev/docs/use-cases/plugin-systems

Demonstrates registering a tool with a schema and handler, then invoking it from within an untrusted plugin execution context.

```typescript
import { NodeRuntime } from "secure-exec";

// Register curated host tools. Their handlers run on the host, so the plugin
// reaches these capabilities only through the tool surface you expose - never
// the underlying database, secrets, or network behind them.
const runtime = await NodeRuntime.create({
  tools: {
    lookupUser: {
      description: "Look up a user by id",
      inputSchema: {
        type: "object",
        properties: { id: { type: "string" } },
        required: ["id"],
      },
      // Runs on the host. In a real system this would hit your database.
      handler: ({ id }: { id: string }) => ({
        id,
        name: id === "u_1" ? "Ada Lovelace" : "Unknown",
      }),
    },
  },
});

try {
  // The untrusted plugin reaches the host capability only through callHostTool,
  // which resolves with the handler's return value.
  const { value } = await runtime.run<{ id: string; name: string }>(`
    const user = await callHostTool("lookupUser", { id: "u_1" });
    __return(user);
  `);

  console.log("looked-up user:", value?.name);
} finally {
  await runtime.dispose();
}
```

--------------------------------

### Configure per-run options

Source: https://secureexec.dev/docs/features/executing-code

Demonstrates passing stdin and a timeout duration to the run() method.

```javascript
const result = await rt.run<string>(
  `
  let input = "";
  for await (const chunk of process.stdin) input += chunk;
  globalThis.__return(input.trim().toUpperCase());
  `,
  { stdin: "piped through stdin", timeout: 10_000 },
);
```

--------------------------------

### Execute guest code with Node.js built-ins

Source: https://secureexec.dev/docs/nodejs-compatibility

Demonstrates importing bridge-backed and polyfilled built-in modules within a guest execution context.

```javascript
import { NodeRuntime } from "secure-exec";

const rt = await NodeRuntime.create();

try {
  const { stdout } = await rt.exec(`
    import path from "node:path";
    import { createHash } from "node:crypto";
    import { writeFileSync, readFileSync } from "node:fs";

    const file = path.join("/tmp", "note.txt");
    writeFileSync(file, "hello");

    const digest = createHash("sha256")
      .update(readFileSync(file))
      .digest("hex");

    console.log(digest);
  `);

  console.log(stdout.trim());
} finally {
  await rt.dispose();
}
```

--------------------------------

### exec(code: string, options?: RunOptions)

Source: https://secureexec.dev/docs/features/executing-code

Executes guest code and resolves with stdout, stderr, and the exit code of the process.

```APIDOC
## exec(code, options)

### Description
Runs the provided guest code string as an ES module and captures the execution output.

### Parameters
- **code** (string) - Required - The JavaScript code to execute.
- **options** (RunOptions) - Optional - Configuration including stdin, env, cwd, timeout, AbortSignal, onStdout, and onStderr.
```

--------------------------------

### Execute untrusted JavaScript in a sandbox

Source: https://secureexec.dev/docs/use-cases/ai-agent-code-exec

Demonstrates booting a NodeRuntime, executing code that returns a structured value via globalThis.__return(), and capturing stdout.

```javascript
import { NodeRuntime } from "secure-exec";

// Imagine this string came from an AI agent. We never trust it: it runs fully
// sandboxed inside the secure-exec VM, with no access to the host machine.
const untrustedCode = `
const fib = [0, 1];
while (fib.length < 20) {
  fib.push(fib[fib.length - 1] + fib[fib.length - 2]);
}
console.log("computed", fib.length, "fibonacci numbers");
// Hand a JSON-serializable value back to the host.
globalThis.__return({ fibonacci: fib, sum: fib.reduce((a, b) => a + b, 0) });
`;

const rt = await NodeRuntime.create();
try {
  // rt.run() executes the guest code and decodes whatever it passes to
  // globalThis.__return(), while still capturing stdout/stderr/exitCode.
  const result = await rt.run<{ fibonacci: number[]; sum: number }>(
    untrustedCode,
    { timeout: 5000 },
  );

  console.log("exitCode:", result.exitCode);
  console.log("stdout:", result.stdout.trim());
  console.log("returned value:", JSON.stringify(result.value));

  // The sandbox presents normal Node semantics, but the code cannot touch the
  // host: it only ever sees the virtual filesystem and kernel-mediated syscalls.
  const escapeAttempt = await rt.exec(
    `import os from "node:os";\nconsole.log("guest hostname:", os.hostname());`,
    { timeout: 5000 },
  );
  console.log("\nescape attempt exitCode:", escapeAttempt.exitCode);
  console.log("escape attempt stdout:", escapeAttempt.stdout.trim());
} finally {
  await rt.dispose();
}
```

--------------------------------

### callHostTool

Source: https://secureexec.dev/docs/features/bindings

Invokes a registered host tool from within the guest environment.

```APIDOC
## callHostTool(name, input)

### Description
Global function available in guest programs to execute a registered host tool. It returns a promise that resolves with the host handler's JSON result.

### Parameters
- **name** (string) - Required - The registered key or command alias of the tool.
- **input** (object) - Required - The input data to pass to the tool handler.
```

--------------------------------

### Return values with run()

Source: https://secureexec.dev/docs/features/output-capture

Uses globalThis.__return() to pass a JSON-decoded value back from the guest process.

```javascript
const { value, exitCode } = await rt.run(`
	const sum = [1, 2, 3].reduce((a, b) => a + b, 0);
	globalThis.__return({ sum });
`);

console.log(exitCode, value); // 0 { sum: 6 }
```

--------------------------------

### Execute Node.js code in a virtualized VM

Source: https://secureexec.dev/docs/features/module-loading

Demonstrates creating a virtualized runtime and executing guest code that uses both ESM imports and CommonJS require.

```javascript
// Boot a fully virtualized VM. Module resolution runs entirely inside the
// kernel - `import` and `require` resolve against the guest's virtual
// filesystem, never the host's.
const rt = await NodeRuntime.create();

try {
  // Guest code runs as an ES module inside the VM, so it can `import` Node
  // builtins directly. It can also build a CommonJS `require` with
  // `createRequire` to load builtins the classic way. Both resolve through the
  // kernel's module loader.
  const { stdout, stderr, exitCode } = await rt.exec(`
    // ESM import of a Node builtin.
    import { basename, join } from "node:path";

    // CommonJS require, created from the current module URL.
    import { createRequire } from "node:module";
    const require = createRequire(import.meta.url);
    const os = require("node:os");

    const resolved = {
      basename: basename("/workspace/data/report.txt"),
      joined: join("/workspace", "data", "report.txt"),
      platform: os.platform(),
    };

    console.log("resolved node:path via import ->", resolved.joined);
    console.log("resolved node:os via require ->", resolved.platform);
    console.log(JSON.stringify(resolved));
  `);

  console.log("exitCode:", exitCode);
  if (stderr.trim()) console.log("guest stderr:\n" + stderr.trim());
  console.log("guest stdout:");
  console.log(stdout.trim());
} finally {
  await rt.dispose();
}
```

--------------------------------

### Probe Node.js runtime environment

Source: https://secureexec.dev/docs/features/runtime-platform

Demonstrates how to verify the presence of Node.js globals and built-in modules from within the isolated runtime.

```typescript
/**
 * Runtime & Platform - what host environment guest JavaScript sees.
 *
 * The `NodeRuntime` façade boots a fully virtualized VM and runs guest code on
 * the **Node platform**: the `process` and `Buffer` globals, `node:*` builtin
 * modules, and full npm-style module resolution are all present. This is the
 * one platform the façade exposes today; the lower-level esbuild-style
 * `platform` knob (browser | neutral | bare) is not surfaced by `NodeRuntime`.
 *
 * This example proves the Node surface is live by having guest code probe its
 * own globals and builtins, then return a structured report to the host.
 */

import { NodeRuntime } from "secure-exec";

const rt = await NodeRuntime.create();

try {
	// Probe the guest's host environment from inside the kernel-backed isolate.
	const probe = await rt.run<{
		platform: string;
		hasProcess: boolean;
		hasBuffer: boolean;
		nodeVersion: string;
		sha256: string;
		joinedPath: string;
	}>(`
		const { createHash } = await import("node:crypto");
		const { join } = await import("node:path");

		const sha256 = createHash("sha256").update("secure-exec").digest("hex");

		globalThis.__return({
			// process/Buffer are Node-platform globals (absent on browser/neutral/bare).
			platform: typeof process !== "undefined" ? process.platform : "(no process)",
			hasProcess: typeof process !== "undefined",
			hasBuffer: typeof Buffer !== "undefined",
			nodeVersion: typeof process !== "undefined" ? process.versions.node : "(none)",
			// node:* builtin modules resolve and run inside the isolate
			// (dynamic import() keeps this snippet a single expression body).
			sha256,
			joinedPath: join("/home/agentos", "report.txt"),
		});
	`);

	if (probe.exitCode !== 0) {
		throw new Error(`guest probe failed (exit ${probe.exitCode}): ${probe.stderr}`);
	}

	const r = probe.value!;
	console.log("Guest host environment (Node platform):");
	console.log(`  process global present : ${r.hasProcess}`);
	console.log(`  Buffer global present  : ${r.hasBuffer}`);
	console.log(`  process.platform       : ${r.platform}`);
	console.log(`  process.versions.node  : ${r.nodeVersion}`);
	console.log(`  node:crypto sha256     : ${r.sha256}`);
	console.log(`  node:path join         : ${r.joinedPath}`);

	// And a plain exec() run, showing stdout capture with the same Node surface.
	const hello = await rt.exec(
		`console.log("hello from", process.platform, "/ Buffer:", Buffer.from("hi").toString("base64"));`,
	);
	console.log("\nexec() stdout:");
	process.stdout.write(`  ${hello.stdout}`);
	console.log(`exec() exitCode: ${hello.exitCode}`);
} finally {
	await rt.dispose();
}
```

--------------------------------

### Run a plugin in isolation

Source: https://secureexec.dev/docs/use-cases/plugin-systems

Demonstrates initializing a NodeRuntime with specific permissions and executing a plugin that returns structured data via globalThis.__return().

```typescript
import { NodeRuntime } from "secure-exec";

// Boot a sandboxed VM for running untrusted plugin code. The plugin can use
// the filesystem, but network access is denied. (childProcess/process stay
// allowed because the kernel spawns the guest `node` process to run the
// plugin - denying it would block the runtime itself.)
const runtime = await NodeRuntime.create({
	permissions: {
		fs: "allow",
		network: "deny",
		childProcess: "allow",
		process: "allow",
		env: "allow",
	},
});

try {
	// The host owns the plugin source and the input. Here the plugin is a
	// title-case transformer; in a real system it would be uploaded by a user.
	const pluginSource = `
		function transform(input, options = {}) {
			const words = String(input)
				.split(/\\s+/)
				.filter(Boolean)
				.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
			return (options.prefix ?? "") + words.join(" ");
		}
		const manifest = { name: "title-case", version: "1.0.0" };
	`;

	const input = "hello from plugin land";
	const options = { prefix: "Plugin says: " };

	// Run the plugin in isolation and get a structured value back via run().
	// The guest calls __return() with a JSON-serializable value, decoded on the
	// host as result.value. The plugin also proves it cannot reach the network.
	const { value, stdout, exitCode } = await runtime.run<{
		manifest: { name: string; version: string };
		output: string;
		networkBlocked: boolean;
	}>(`
		${pluginSource}

		console.log("running plugin:", manifest.name);

		let networkBlocked = false;
		try {
			await fetch("http://example.com");
		} catch {
			networkBlocked = true;
		}

		__return({
			manifest,
			output: transform(${JSON.stringify(input)}, ${JSON.stringify(options)}),
			networkBlocked,
		});
	`);

	console.log("guest stdout:", stdout.trim());
	console.log("exit code:", exitCode);
	console.log("plugin name:", value?.manifest.name);
	console.log("plugin version:", value?.manifest.version);
	console.log("plugin output:", value?.output);
	console.log("network blocked:", value?.networkBlocked);
} finally {
	await runtime.dispose();
}
```

--------------------------------

### Benchmark Environment Specifications

Source: https://secureexec.dev/docs/benchmarks

Hardware and software configuration used for performance measurements.

```text
CPU:   12th Gen Intel(R) Core(TM) i7-12700KF
Cores: 20 | Max concurrency: 16 | Max live runtimes: 8
RAM:   62.6 GB | Node: v24.13.0
Iterations: 5 (+ 1 warmup)
Batch sizes: 1, 10, 50, 100, 200
Scenarios: owned-sidecar, shared-sidecar, resident-runner
Sidecar: release build of secure-exec-sidecar
```

--------------------------------

### Stream output from a guest process

Source: https://secureexec.dev/docs/features/child-processes

Uses onStdout to handle streaming output from a process and demonstrates manual termination with kill.

```typescript
const proc = await rt.spawn("setInterval(() => console.log('tick'), 100)", {
  onStdout: (chunk) => process.stdout.write(new TextDecoder().decode(chunk)),
});
// ... later
proc.kill();              // SIGTERM
await proc.wait();
```

--------------------------------

### Spawn a long-running guest process

Source: https://secureexec.dev/docs/features/child-processes

Demonstrates spawning a process that reads from stdin and writes to stdout, then waiting for its completion.

```typescript
const proc = await rt.spawn(`
  process.stdin.on("data", (chunk) => {
    process.stdout.write("got: " + chunk.toString());
  });
`);

proc.writeStdin("hello\n");   // feed stdin
proc.closeStdin();            // signal end-of-input

const exitCode = await proc.wait();
console.log(proc.pid, exitCode);
```

--------------------------------

### HostToolDefinition

Source: https://secureexec.dev/docs/features/bindings

Defines the structure for registering a tool on the host runtime.

```APIDOC
## HostToolDefinition

### Description
A configuration object used to register a tool within the NodeRuntime. It defines the tool's schema, execution logic, and metadata.

### Fields
- **description** (string) - Required - Human-readable summary of what the tool does.
- **inputSchema** (object) - Required - JSON Schema describing the expected input.
- **handler** (function) - Required - The function that runs on the host, returning a JSON-serializable value.
- **timeoutMs** (number) - Optional - Abort the host handler after this many milliseconds.
- **examples** (array) - Optional - Worked examples shown alongside the tool.
- **commandAliases** (array) - Optional - Extra command names the guest may use.
```

--------------------------------

### Drive a guest server

Source: https://secureexec.dev/docs/features/child-processes

Spawns a server process, waits for it to listen on a specific port, and performs internal requests using rt.fetch.

```typescript
const server = await rt.spawn(`
  import http from "node:http";
  http.createServer((_, res) => res.end("ok")).listen(3000);
`);

const listener = await rt.waitForListener({ port: 3000 });
const res = await rt.fetch(listener.port ?? 3000, { path: "/" });
console.log(res.status, res.body); // 200 ok

server.kill();
await server.wait();
```

--------------------------------

### Execution output for npm package loading

Source: https://secureexec.dev/docs/features/module-loading

The expected console output after successfully loading and executing the is-number package inside the VM.

```text
exitCode: 0
guest stdout:
loaded real npm package is-number
{"isNumber(42)":true,"isNumber("3.14")":true,"isNumber("nope")":false,"sameModule":true}
```

--------------------------------

### Define a Host Tool

Source: https://secureexec.dev/docs/features/bindings

Register a tool with the NodeRuntime, including its schema, handler, and optional metadata like aliases and timeouts.

```typescript
const rt = await NodeRuntime.create({
  tools: {
    lookupWeather: {
      description: "Look up the current weather for a city",
      inputSchema: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
      },
      timeoutMs: 5000,
      examples: [{ description: "Weather in Tokyo", input: { city: "Tokyo" } }],
      commandAliases: ["weather"],
      handler: async ({ city }: { city: string }) => {
        // Real host access lives here, behind the tool boundary. The guest
        // never gets the network credential, only the curated result.
        const res = await fetch(`https://example.com/weather?city=${city}`);
        return await res.json();
      },
    },
  },
});
```

--------------------------------

### Drive a guest dev server from the host

Source: https://secureexec.dev/docs/features/runtime-platform

Spawns a guest process, waits for a specific port to become active, and performs an HTTP request through the kernel socket table.

```typescript
const server = await rt.spawn(`
	import http from "node:http";
	http.createServer((_, res) => res.end("ok")).listen(3000);
`);
const listener = await rt.waitForListener({ port: 3000 });
const res = await rt.fetch(listener.port ?? 3000, { path: "/" });
server.kill();
await server.wait();
```

--------------------------------

### Invoke a Tool via callHostTool

Source: https://secureexec.dev/docs/features/bindings

Use the global callHostTool function within guest code to execute a registered tool and receive its JSON result.

```javascript
await rt.exec(`
  const { temp_f } = await callHostTool("get-weather", { city: "Tokyo" });
  console.log(temp_f); // 75
`);
```

--------------------------------

### Add secure-exec-client to Cargo.toml

Source: https://secureexec.dev/docs/sdks/rust

Manually add the dependency to your Cargo.toml file.

```toml
[dependencies]
secure-exec-client = "*"
```

--------------------------------

### Run Guest Code and Return Values

Source: https://secureexec.dev/docs/quickstart

Executes guest JavaScript as an ES module and retrieves a value returned via globalThis.__return().

```typescript
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();
}
```

--------------------------------

### Configure WASM Command Directory

Source: https://secureexec.dev/docs/features/child-processes

Sets a custom directory for loading WASM-backed command binaries during runtime initialization.

```javascript
const rt = await NodeRuntime.create({
  commandsDir: "/path/to/wasm/commands",
});
```
Tokens:
Raw