run is an alternative to eval for coding agents, with support for
TypeScript. Use it for code-mode, code interpreters, and other patterns that
execute untrusted JS or TS.
run executes JavaScript in a hardened QuickJS sandbox. Guest code starts with
no access to Node.js, the filesystem, environment variables, modules, or the
network; it can call only the host functions you explicitly provide.
Host functions can be any normal JavaScript or TypeScript functions. They can
also interrupt execution for approval or authentication and resume later without
repeating already invoked host functions.
Install
pnpm add run
run supports Node.js 20.19 or newer and Bun.
Run JavaScript
import { run } from 'run';const result = await run({ source: ` const total = await tools.sum(1, 2, 3, 4); return { total }; `,
Arguments cross the QuickJS boundary as one serialized array. Their count and
positions are preserved, including explicit undefined arguments.
Values across the sandbox boundary
run uses the versioned run-js-v1 format in both directions. It supports:
primitives, including undefined, BigInt, NaN, infinities, and -0;
plain objects, arrays, sparse arrays, cycles, and repeated references;
Date, RegExp, Map, and Set;
ArrayBuffer, DataView, and typed arrays; and
Error values, including name, message, cause, and
AggregateError.errors.
References are preserved within one transferred value graph. Separate host
function calls are separate transfers and do not share object identity. Plain
objects are reconstructed as plain objects rather than retaining custom
prototypes. Error stacks are regenerated in the receiving realm and are not
transferred.
Functions, symbols, promises, weak collections, and arbitrary class instances
cannot cross the boundary. Returning one fails with a serialization error that
includes its path when available. Keep capabilities in host functions and send
data through their arguments and results.
Synchronous host functions
Use syncHostFunctions when guest APIs must return before the next guest
statement runs, such as filesystem compatibility methods. The host handler may
still be asynchronous; run blocks only the invocation's worker while it
settles and returns the serialized value directly to guest code.
Synchronous host functions must settle to a serializable value and cannot
interrupt a run. Their calls share maxBridgeRequests with ordinary host
functions. Forward getHostFunctionContext().abortSignal to cancellable work;
the signal is aborted on timeout or caller cancellation. The synchronous bridge
is allocated only for runs that configure synchronous bindings or a module
loader, is included in invocation memory admission, and is capped at 64 MiB.
Native ES modules
Passing moduleLoader enables native module resolution. For compatibility,
its presence evaluates source as an ES module unless sourceType is set
explicitly. Module source supports static, cyclic, and dynamic imports:
Set sourceType: 'function-body' to retain top-level await, return, and a
serialized run value while enabling native dynamic imports:
const result = await runner.run({ source: ` const { value } = await import('./value.js'); return value; `, sourceType: 'function-body', moduleLoader,});
Set sourceType: 'module' to evaluate an entry module even when it has no
imports and no module loader. Entry modules execute for their side effects and
a completed module run has value: undefined; the module namespace is not
serialized as the run result.
normalize and load may be synchronous or asynchronous. Their results are
bounded by the host-function bridge limits, and SharedArrayBuffer and
Atomics remain unavailable to guest JavaScript. Module-backed runs can create
and resume continuations when the loader has a non-empty stable identity.
Loader failures are redacted before entering the sandbox.
This allows modules to export functions and cyclic namespaces without turning
those exports into result-serialization failures.
Native Node type stripping is used when the runtime provides it, and Bun uses
its native TypeScript transpiler. On Node 20, install the optional typescript
peer dependency to enable runtime type stripping. Without that peer, JavaScript
and already type-stripped input remain supported and QuickJS reports unsupported
TypeScript syntax without exposing a host module-resolution error.
Host function context
Call getHostFunctionContext() when a host function needs runtime metadata,
cancellation, or interruption. Context is not a guest argument, so the host
function signature continues to match the call made in sandboxed JavaScript.
The context is isolated for each concurrent host function call and follows
awaited asynchronous work. getHostFunctionContext() throws outside an active
host function and from detached work after the host function settles or is
aborted.
HostFunctionContext contains:
Property
Meaning
abortSignal
Aborted when the run is cancelled, times out, or fails
hostFunctionName
Fully qualified name such as tools.sum
logicalRunId
Stable across every continuation replay
invocationId
Identifies the current execution attempt
requestId
Identifies this host function request in the current attempt
requestIndex
One-based host function request order
interrupt(payload)
Suspends the run; its return type is never
resume
Resolution metadata when an interrupted host function is replayed
Interrupt and resume
Host functions can pause a run before a protected operation. Configure one
shared secret for every process that can create or resume continuations:
Ordinary runs need no continuation configuration. If a host function interrupts
without RUN_CONTINUATION_SECRET, continuationSecret, or a
continuationCodec, the run fails with a configuration error.
See Continuations for replay behavior, multi-process
deployment, multiple interruptions, storage-backed tokens, and key rotation.
Configure a runner
Use createRunner() to share limits and continuation configuration:
continuationSecret must contain at least 32 bytes. It takes precedence over
the environment variable. Supplying both continuationSecret and
continuationCodec is an error.
Per-run limits override runner defaults. An abortSignal cancels an active
invocation and is available through getHostFunctionContext().
Limit
Default
Timeout (timeoutMs)
30 seconds
CPU timeout (cpuTimeoutMs)
10 seconds
QuickJS memory
64 MiB
QuickJS stack
2 MiB
Source
256 KiB
Result
1 MiB
Console output
64 KiB
Host function arguments
1 MiB
Host function output or interruption payload
4 MiB
Bridge requests
256
Concurrent bridge requests
32
Continuation
32 MiB
timeoutMs is the wall-clock ceiling for one invocation, including time spent
waiting on host functions, module loaders, and continuation codecs. It fails
with RUN_TIMEOUT. cpuTimeoutMs bounds the time the worker spends running
guest JavaScript in one invocation and fails with RUN_CPU_TIMEOUT. Time spent
awaiting asynchronous host functions or blocked in synchronous host functions
and module loaders does not count toward it. To allow slow host functions,
raise timeoutMs and rely on cpuTimeoutMs to stop runaway guest code. Guest
time never exceeds wall time, so cpuTimeoutMs only takes effect when it is
lower than timeoutMs; the defaults leave 20 seconds of wall time for host
waits. Each invocation, including each continuation resume, starts with a fresh
CPU budget. A pending interruption never hides an exceeded budget: the
invocation fails instead of returning a continuation.
All limits must be positive integers no greater than 2_147_483_647. Values
above this ceiling are rejected instead of being passed to platform APIs that
cannot represent them safely. The process-wide worker cap rejects excess
invocations with RunConcurrencyError; run does not retain an unbounded
queue. The cap and worker pool are shared by every runner and by packages such
as @ai-sdk/code-mode in the same process.
Continuations
Multi-process signing
Set the same RUN_CONTINUATION_SECRET on every server instance, worker, and
resume endpoint. The convenience run() function and runners without explicit
continuation options use it automatically. This lets any process verify and
resume a continuation produced by another process or by an earlier deployment
instance.
For application-managed configuration, pass the same continuationSecret to
each runner. For custom expiry or signing-key rotation, construct the codec
directly:
New tokens use only secret; verificationSecrets are accepted only while
verifying old tokens.
Replay behavior
A continuation contains a replay ledger. On resume, completed and rejected
asynchronous host functions, synchronous host functions, and module-loader
operations are read from that ledger instead of being invoked again. The
runtime reinvokes only interrupted host functions that now have a resolution;
operations first reached after the recorded frontier dispatch normally.
Replay verifies the source, asynchronous and synchronous host-function-name
manifests, module-loader identity, and complete serialized argument list for
every bridge call. Guest Date, Date.now(), and Math.random() remain
deterministic across replay. Divergence is rejected before a mismatched
integration executes.
Replay runs the guest source again from the start. That guest work counts
toward the resumed invocation's cpuTimeoutMs, which starts from zero on every
resume.
An interrupted host function itself is reinvoked. Call interrupt() before
doing non-idempotent work. For writes that may be retried, use
getHostFunctionContext().resume.interruptionId as a stable idempotency key.
interrupt() uses an internal throw. Do not catch it inside the host function.
The runtime catches it at the host boundary and returns an interrupted result.
Multiple interruptions
Concurrent host function calls may interrupt together. The result contains the
full batch and one continuation:
const result = await run({ source: ` return await Promise.all([ actions.deleteAccount('account-1'), actions.sendPayment('payment-1'), ]); `, hostFunctions,});if (result.status === 'interrupted') { // This example resolves the full batch after collecting every approval. await run({ source, hostFunctions, continuation: result.continuation, resolutions: result.interruptions.map(interruption => ({ interruptionId: interruption.id, value: approvals[interruption.id], })), });}
You can instead resume with resolutions for any non-empty subset of the batch.
Calls without a resolution remain pending with the same IDs and payloads,
without invoking their host functions again. Resolved branches can advance and
reach new interruptions. If the run remains interrupted, use its returned
continuation and pending interruptions for the next resume so completed work
is preserved. Each interruption also exposes the complete guest call as its
arguments array.
Scope and authorization
Signed continuations are bound to the runner audience, source, asynchronous and
synchronous host-function-name manifests, module-loader identity, and
continuationContext. For tenant-, user-, or policy-scoped execution, provide
authenticated context on both the initial run and every resume:
A mismatch is rejected before replayed results are returned or an interrupted
host function is reinvoked. The resume endpoint must still authorize the actor
who submits each resolution. A valid continuation proves integrity and scope;
it does not grant approval by itself.
Token security and storage
Signed continuations are self-contained, replayable bearer tokens. They
provide integrity, not confidentiality: source, arguments, results, errors,
and interruption payloads are base64-encoded but not encrypted.
For sensitive or at-most-once flows, use createStoredContinuationCodec().
Its storage contract temporarily claims a token during decode and enforces
expiry. Cancellation and replay-validation failures release the claim; valid
continuations are consumed before worker execution. Claims must expire after a
bounded interval so process failure cannot permanently strand a token.
A custom continuation codec used across a trust boundary must authenticate
its state and reject tampering. An unauthenticated codec lets an attacker
forge completed effects and resume payloads. Prefer the signed or
storage-backed codecs unless a custom implementation provides equivalent
integrity and scope validation.
Custom codecs receive versioned replay state plus an operation context with an
abortSignal and deadlineMs. Treat continuation tokens as opaque; the replay
state is an advanced API that may evolve between releases.
Replay state identifies its value codec as run-js-v1. Serialized host
function arguments, results, interruption payloads, and resolutions remain
opaque strings inside the JSON continuation envelope, so rich and cyclic values
do not weaken canonical signing. Ledger entries use the wire property name
bindingName as the persisted host function path key.
Security model
Sandboxed code has no ambient access to Node.js, the filesystem, environment
variables, modules, network APIs, timers, crypto, or high-resolution clocks.
Dynamic evaluation is disabled and built-in prototypes are frozen. Host access
is limited to declared host functions and serialized values crossing the worker
boundary.
Host function groups and functions must be own properties. Inherited prototype
members are never capabilities. Guest namespaces cannot replace JavaScript
builtins or runtime internals.
Resource limits reduce denial-of-service risk, but host functions remain
security-sensitive capabilities. Validate authentication, authorization, and
application input in the host environment.
Errors and retries
Runtime failures extend RunError and expose a stable code:
RUN_ABORTED, RUN_TIMEOUT, and RUN_CONCURRENCY_LIMIT may be retried when
host effects are safe to retry.
RUN_CPU_TIMEOUT means guest JavaScript exceeded cpuTimeoutMs. Retrying
unchanged source usually fails again.
RUN_PROTOCOL_ERROR indicates malformed, tampered, expired, or divergent
continuation state. Do not retry unchanged input.
RUN_USER_SOURCE_ERROR identifies uncaught guest evaluation failures, including
syntax errors and thrown values. Guest-authored code properties are replaced;
trusted host and runtime codes are preserved.
RUN_HOST_FUNCTION_ERROR comes from capability lookup or host function
execution.
RUN_BRIDGE_LIMIT, RUN_SOURCE_TOO_LARGE, and serialization failures require
changing the source, values, or limits.
RUN_DETACHED_BRIDGE_REQUEST means guest code returned without correctly
awaiting bridge work.
Syntax and runtime error stacks use run.js and line numbers from the exact
source string passed to run. Generated wrapper and sandbox-runtime frames
are omitted. The same coordinates are retained after supported TypeScript
syntax is stripped and when an awaited host function rejects:
Error: calculation failed at calculate (run.js:4:9) at <anonymous> (run.js:7:16)
Columns are reported by QuickJS. Stacks belonging to Error objects returned
as ordinary data are not transferred; this stack behavior applies to errors
that escape execution.
Workers that cannot reach a verified clean state after abort, timeout, protocol
failure, or detached work are retired. Every invocation receives a fresh
QuickJS context, including invocations on reused worker threads.