feat: update quickstart examples to use ESM and NodeRuntime API

All quickstart examples now use ESM syntax (import/export) instead of
CJS (require/module.exports) and the NodeRuntime API instead of the
kernel API. Adds a new multi-file ESM example showing VFS imports.

Author: NathanFlurry

docs-internal/todo.md

@@ -169,6 +169,8 @@ docs-internal/specs/cli-tool-e2e.md
 
 - [x] Define the minimal driver surface needed for Rivet integration. *(done — `RuntimeDriver` interface in `packages/kernel/src/types.ts`)*
 
+- [ ] Support long-running processes (e.g. dev servers) without `await new Promise(() => {})` — sandbox should keep exec alive while active handles (listeners, timers) exist, matching Node's event loop semantics.
+
 - [ ] Add a codemode example.
   - Provide a focused example that demonstrates secure-exec usage in a realistic tool flow.
   - Files: `examples/`

docs/quickstart.mdx

@@ -46,7 +46,7 @@ icon: "rocket"
     Use `runtime.run()` to execute JavaScript and get back exported values. Use `runtime.exec()` for scripts that produce console output.
 
     <CodeGroup>
-      ```ts Run & Get Exports
+      ```ts Simple
       import {
         NodeRuntime,
         createNodeDriver,
@@ -59,15 +59,15 @@ icon: "rocket"
       });
 
       const result = await runtime.run<{ message: string }>(
-        `module.exports = { message: "hello from secure-exec" };`
+        `export const message = "hello from secure-exec";`
       );
 
       console.log(result.exports?.message); // "hello from secure-exec"
 
       runtime.dispose();
       ```
 
-      ```ts Execute & Capture Output
+      ```ts Logging
       import {
         NodeRuntime,
         createNodeDriver,
@@ -105,24 +105,24 @@ icon: "rocket"
       const runtime = new NodeRuntime({
         systemDriver: createNodeDriver({
           filesystem,
-          permissions: { fs: allowAllFs },
+          permissions: { ...allowAllFs },
         }),
         runtimeDriverFactory: createNodeRuntimeDriverFactory(),
       });
 
       await runtime.exec(`
-        const fs = require("node:fs");
+        import fs from "node:fs";
         fs.mkdirSync("/workspace", { recursive: true });
         fs.writeFileSync("/workspace/hello.txt", "hello from the sandbox");
-      `);
+      `, { filePath: "/entry.mjs" });
 
       const bytes = await filesystem.readFile("/workspace/hello.txt");
       console.log(new TextDecoder().decode(bytes)); // "hello from the sandbox"
 
       runtime.dispose();
       ```
 
-      ```ts Network Access
+      ```ts Fetch
       import {
         NodeRuntime,
         createNodeDriver,
@@ -132,7 +132,7 @@ icon: "rocket"
 
       const runtime = new NodeRuntime({
         systemDriver: createNodeDriver({
-          permissions: { network: allowAllNetwork },
+          permissions: { ...allowAllNetwork },
         }),
         runtimeDriverFactory: createNodeRuntimeDriverFactory(),
         onStdio: (event) => {
@@ -148,24 +148,48 @@ icon: "rocket"
       runtime.dispose();
       ```
 
-      ```ts ESM Modules
+      ```ts Multi-File
       import {
         NodeRuntime,
         createNodeDriver,
         createNodeRuntimeDriverFactory,
+        createInMemoryFileSystem,
+        allowAllFs,
       } from "secure-exec";
 
+      const filesystem = createInMemoryFileSystem();
+
+      // Write module files to the virtual filesystem
+      await filesystem.writeFile(
+        "/app/math.mjs",
+        `export function add(a, b) { return a + b; }`
+      );
+      await filesystem.writeFile(
+        "/app/greet.mjs",
+        `export function greet(name) { return "hello, " + name; }`
+      );
+
       const runtime = new NodeRuntime({
-        systemDriver: createNodeDriver(),
+        systemDriver: createNodeDriver({
+          filesystem,
+          permissions: { ...allowAllFs },
+        }),
         runtimeDriverFactory: createNodeRuntimeDriverFactory(),
       });
 
-      const result = await runtime.run<{ answer: number }>(
-        `export const answer = 42;`,
-        "/entry.mjs" // .mjs extension triggers ESM mode
+      const result = await runtime.run<{ sum: number; greeting: string }>(
+        `
+        import { add } from "./math.mjs";
+        import { greet } from "./greet.mjs";
+
+        export const sum = add(1, 2);
+        export const greeting = greet("secure-exec");
+        `,
+        "/app/entry.mjs"
       );
 
-      console.log(result.exports?.answer); // 42
+      console.log(result.exports?.sum);      // 3
+      console.log(result.exports?.greeting); // "hello, secure-exec"
 
       runtime.dispose();
       ```

examples/quickstart/scripts/verify-docs.mjs

@@ -8,12 +8,10 @@ const docsPath = path.join(repoRoot, "docs/quickstart.mdx");
 
 const expectedFiles = new Map([
   ["Simple", "src/simple.ts"],
-  ["TypeScript", "src/typescript.ts"],
   ["Logging", "src/logging.ts"],
   ["Filesystem", "src/filesystem.ts"],
   ["Fetch", "src/fetch.ts"],
-  ["HTTP Server (Hono)", "src/http-server-hono.ts"],
-  ["Run Command", "src/run-command.ts"],
+  ["Multi-File", "src/multi-file.ts"],
 ]);
 
 function normalizeTitle(title) {

examples/quickstart/src/fetch.ts

@@ -1,24 +1,23 @@
 import {
-  createKernel,
-  createInMemoryFileSystem,
-  createNodeRuntime,
+  NodeRuntime,
+  createNodeDriver,
+  createNodeRuntimeDriverFactory,
+  allowAllNetwork,
 } from "secure-exec";
 
-const kernel = createKernel({
-  filesystem: createInMemoryFileSystem(),
-  permissions: {
-    network: () => ({ allow: true }),
+const runtime = new NodeRuntime({
+  systemDriver: createNodeDriver({
+    permissions: { ...allowAllNetwork },
+  }),
+  runtimeDriverFactory: createNodeRuntimeDriverFactory(),
+  onStdio: (event) => {
+    process.stdout.write(event.message);
   },
 });
-await kernel.mount(createNodeRuntime());
 
-const result = await kernel.exec(`node -e "
-  (async () => {
-    const response = await fetch('https://example.com');
-    console.log(response.status);
-  })();
-"`);
+await runtime.exec(`
+  const response = await fetch("https://example.com");
+  console.log(response.status); // 200
+`);
 
-console.log(result.stdout); // "200\n"
-
-await kernel.dispose();
+runtime.dispose();

examples/quickstart/src/filesystem.ts

@@ -1,25 +1,28 @@
 import {
-  createKernel,
+  NodeRuntime,
+  createNodeDriver,
+  createNodeRuntimeDriverFactory,
   createInMemoryFileSystem,
-  createNodeRuntime,
+  allowAllFs,
 } from "secure-exec";
 
 const filesystem = createInMemoryFileSystem();
-const kernel = createKernel({
-  filesystem,
-  permissions: {
-    fs: () => ({ allow: true }),
-  },
+
+const runtime = new NodeRuntime({
+  systemDriver: createNodeDriver({
+    filesystem,
+    permissions: { ...allowAllFs },
+  }),
+  runtimeDriverFactory: createNodeRuntimeDriverFactory(),
 });
-await kernel.mount(createNodeRuntime());
 
-await kernel.exec(`node -e "
-  const fs = require('node:fs');
-  fs.mkdirSync('/workspace', { recursive: true });
-  fs.writeFileSync('/workspace/hello.txt', 'hello from the sandbox');
-"`);
+await runtime.exec(`
+  import fs from "node:fs";
+  fs.mkdirSync("/workspace", { recursive: true });
+  fs.writeFileSync("/workspace/hello.txt", "hello from the sandbox");
+`, { filePath: "/entry.mjs" });
 
 const bytes = await filesystem.readFile("/workspace/hello.txt");
 console.log(new TextDecoder().decode(bytes)); // "hello from the sandbox"
 
-await kernel.dispose();
+runtime.dispose();

examples/quickstart/src/http-server-hono.ts

@@ -18,17 +18,15 @@ const runtime = new NodeRuntime({
 
 // Start a Hono server inside the sandbox
 const execPromise = runtime.exec(`
-  (async () => {
-    const { Hono } = require("hono");
-    const { serve } = require("@hono/node-server");
+  import { Hono } from "hono";
+  import { serve } from "@hono/node-server";
 
-    const app = new Hono();
-    app.get("/", (c) => c.text("hello from hono"));
+  const app = new Hono();
+  app.get("/", (c) => c.text("hello from hono"));
 
-    serve({ fetch: app.fetch, port: ${port}, hostname: "127.0.0.1" });
-    await new Promise(() => {});
-  })();
-`);
+  serve({ fetch: app.fetch, port: ${port}, hostname: "127.0.0.1" });
+  await new Promise(() => {});
+`, { filePath: "/app/server.mjs" });
 
 // Wait for the server to be ready, then fetch from the host
 const url = "http://127.0.0.1:" + port + "/";

examples/quickstart/src/logging.ts

@@ -1,19 +1,21 @@
 import {
-  createKernel,
-  createInMemoryFileSystem,
-  createNodeRuntime,
+  NodeRuntime,
+  createNodeDriver,
+  createNodeRuntimeDriverFactory,
 } from "secure-exec";
 
-const kernel = createKernel({
-  filesystem: createInMemoryFileSystem(),
+const runtime = new NodeRuntime({
+  systemDriver: createNodeDriver(),
+  runtimeDriverFactory: createNodeRuntimeDriverFactory(),
+  onStdio: (event) => {
+    process.stdout.write(event.message);
+  },
 });
-await kernel.mount(createNodeRuntime());
 
-const result = await kernel.exec(
-  "node -e \"console.log('hello from secure-exec')\""
-);
+const result = await runtime.exec(`
+  console.log("hello from secure-exec");
+`);
 
-console.log(result.stdout); // "hello from secure-exec\n"
-console.log(result.stderr); // ""
+console.log("exit code:", result.code); // 0
 
-await kernel.dispose();
+runtime.dispose();

examples/quickstart/src/multi-file.ts

@@ -0,0 +1,43 @@
+import {
+  NodeRuntime,
+  createNodeDriver,
+  createNodeRuntimeDriverFactory,
+  createInMemoryFileSystem,
+  allowAllFs,
+} from "secure-exec";
+
+const filesystem = createInMemoryFileSystem();
+
+// Write module files to the virtual filesystem
+await filesystem.writeFile(
+  "/app/math.mjs",
+  `export function add(a, b) { return a + b; }`
+);
+await filesystem.writeFile(
+  "/app/greet.mjs",
+  `export function greet(name) { return "hello, " + name; }`
+);
+
+const runtime = new NodeRuntime({
+  systemDriver: createNodeDriver({
+    filesystem,
+    permissions: { ...allowAllFs },
+  }),
+  runtimeDriverFactory: createNodeRuntimeDriverFactory(),
+});
+
+const result = await runtime.run<{ sum: number; greeting: string }>(
+  `
+  import { add } from "./math.mjs";
+  import { greet } from "./greet.mjs";
+
+  export const sum = add(1, 2);
+  export const greeting = greet("secure-exec");
+  `,
+  "/app/entry.mjs"
+);
+
+console.log(result.exports?.sum);      // 3
+console.log(result.exports?.greeting); // "hello, secure-exec"
+
+runtime.dispose();

examples/quickstart/src/run-command.ts

@@ -1,22 +1,23 @@
 import {
-  createKernel,
-  createInMemoryFileSystem,
-  createNodeRuntime,
+  NodeRuntime,
+  createNodeDriver,
+  createNodeRuntimeDriverFactory,
+  allowAllChildProcess,
 } from "secure-exec";
 
-const kernel = createKernel({
-  filesystem: createInMemoryFileSystem(),
-  permissions: {
-    childProcess: () => ({ allow: true }),
+const runtime = new NodeRuntime({
+  systemDriver: createNodeDriver({
+    permissions: { ...allowAllChildProcess },
+  }),
+  runtimeDriverFactory: createNodeRuntimeDriverFactory(),
+  onStdio: (event) => {
+    process.stdout.write(event.message);
   },
 });
-await kernel.mount(createNodeRuntime());
 
-const result = await kernel.exec(`node -e "
-  const { execSync } = require('node:child_process');
-  console.log(execSync('node --version', { encoding: 'utf8' }).trim());
-"`);
+await runtime.exec(`
+  import { execSync } from "node:child_process";
+  console.log(execSync("node --version", { encoding: "utf8" }).trim());
+`, { filePath: "/entry.mjs" });
 
-console.log(result.stdout); // e.g. "v22.x.x\n"
-
-await kernel.dispose();
+runtime.dispose();

examples/quickstart/src/simple.ts

@@ -1,18 +1,18 @@
 import {
-  createKernel,
-  createInMemoryFileSystem,
-  createNodeRuntime,
+  NodeRuntime,
+  createNodeDriver,
+  createNodeRuntimeDriverFactory,
 } from "secure-exec";
 
-const kernel = createKernel({
-  filesystem: createInMemoryFileSystem(),
+const runtime = new NodeRuntime({
+  systemDriver: createNodeDriver(),
+  runtimeDriverFactory: createNodeRuntimeDriverFactory(),
 });
-await kernel.mount(createNodeRuntime());
 
-const result = await kernel.exec(
-  "node -e \"console.log('hello from secure-exec')\""
+const result = await runtime.run<{ message: string }>(
+  `export const message = "hello from secure-exec";`
 );
 
-console.log(result.stdout); // "hello from secure-exec\n"
+console.log(result.exports?.message); // "hello from secure-exec"
 
-await kernel.dispose();
+runtime.dispose();