Quickstart

1. Install

   npm

   npm install secure-exec

   bun

   bun add secure-exec

   pnpm

   pnpm add secure-exec

   yarn

   yarn add secure-exec

2. 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 /home/user, and permissions default to a secure policy that denies network access (see step 4).

   import { NodeRuntime } from "secure-exec";
   
   const runtime = await NodeRuntime.create();

3. 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.

   Return a value

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

   Capture output

   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

4. 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.

Next steps

Crash Course A fast tour of the essential SDK API and core concepts.

Permissions Control filesystem, network, and process access.