run

run is a TypeScript package for executing untrusted JavaScript and TypeScript without giving it direct access to your application or system.

Use it for coding agents, code interpreters, and anything else that executes generated code. Each invocation runs in a hardened QuickJS sandbox with no ambient access to Node.js, the filesystem, environment variables, modules, or the network.

How it works

Your application passes source code and a set of host functions to run. Host functions are ordinary JavaScript or TypeScript functions that define the capabilities available inside the sandbox.

The sandbox can only interact with the outside world through the host functions you provide. Arguments and return values are serialized across the sandbox boundary, and every invocation uses a fresh QuickJS context inside a worker thread.

A host function can also interrupt execution when the workflow needs an approval or an authentication step. The run resumes from a signed continuation without repeating host functions that already completed.

Install

pnpm add run

run requires Node.js 22.13 or newer.

Run your first program

import { run } from 'run';

const result = await run({
  source: `
    const doubled = await tools.double(21);
    return { message: 'Hello from the sandbox!', doubled };
  `,
  hostFunctions: {
    tools: {
      double: (value: number) => value * 2,
    },
  },
});

if (result.status === 'completed') {
  console.log(result.value);
}

The tools host function group becomes a global named tools inside the sandbox, so tools.double(21) calls the host function with those arguments and returns its result to the guest.

Core APIs

• run() executes source code with host functions and per-run options.
• createRunner() creates a reusable runner with shared limits and continuation configuration.
• getHostFunctionContext() gives an active host function access to cancellation, invocation metadata, interruptions, and resume data.