---
title: QuickJS Runtime
description: Keep long-running workflows fast by resuming from a saved snapshot instead of replaying every event.
docs_index: /llms.txt
lastUpdated: 2026-11-18
type: guide
summary: Run workflow functions on the QuickJS runtime with snapshotting so resume cost stays flat and runs are exempt from the per-run event limit.
prerequisites:
  - /docs/how-it-works/event-sourcing
related:
  - "/docs/configuration/runtime-tuning#workflow_vm"
  - /docs/errors/max-events-exceeded
  - /docs/errors/replay-timeout
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Every time a workflow resumes, it re-executes from the top and replays its [event log](/docs/how-it-works/event-sourcing) to get back to where it left off. That takes milliseconds for most runs. For agents, chat sessions, and loops that run for days, the log keeps growing, so each resume gets slower and the run eventually fails with [`MAX_EVENTS_EXCEEDED`](/docs/errors/max-events-exceeded) or [`REPLAY_TIMEOUT`](/docs/errors/replay-timeout).

The QuickJS runtime fixes this. It runs your workflow functions in a [QuickJS](https://github.com/quickjs-ng/quickjs) VM instead of the default `node:vm` context and, once a run has processed 1,000 events, saves the VM's memory when the run suspends. The next resume restores that snapshot and replays only the events recorded since, so resume cost stays roughly flat however long the run gets. Runs on the QuickJS runtime with snapshotting are also exempt from the default per-run event limit.

Step functions are not affected. They always run with full Node.js access.

## Enable it

Set `WORKFLOW_VM=quickjs` in the environment that starts runs, which is the process that calls [`start()`](/docs/api-reference/workflow-api/start):

```bash
WORKFLOW_VM=quickjs
```

Snapshotting is on by default under QuickJS, so that is the only variable you need. See [Tuning](#tuning) to change how often a run snapshots.

> The exemption from the per-run event limit needs `workflow` 5.2.3 or later. Earlier versions snapshot the same way, but only record the snapshot policy on the run when you also set `WORKFLOW_SNAPSHOT_THRESHOLD`.

Only runs started after the change use the QuickJS runtime. A run keeps the VM and snapshot policy it started with, so runs already in progress are not changed, and a run that already failed is not revived. Start it again.

The setting applies to every workflow the process starts.

### World support

Snapshots are stored by your World, next to the run's event log:

| World                       | Snapshots            | Notes                                                                                                                                                                                                            |
| --------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vercel World                | Encrypted            | Each run has an encryption key, and its snapshots are encrypted and authenticated with it.                                                                                                                       |
| Local World, Postgres World | Plaintext            | Runs have no encryption key, so snapshots are stored the same way as the event log and payloads. Protect snapshot storage like the rest of the World's storage.                                                  |
| Other Worlds                | Depends on the World | A World that implements snapshot storage snapshots by default, encrypted when it provides a run encryption key. Without snapshot storage, runs still execute on QuickJS and replay the full log on every resume. |

The exemption from the per-run event limit applies on the Local World and the Vercel World.

## Check your workflow code first

QuickJS does not provide a few globals inside workflow functions. If your workflow functions use any of these, move the call into a step:

| Not available in workflow functions                                           | What to do             |
| ----------------------------------------------------------------------------- | ---------------------- |
| `Intl.*`, and `toLocaleString()`-style methods called with an explicit locale | Format in a step       |
| `crypto.subtle.*`, including `digest`                                         | Hash or sign in a step |
| `WebAssembly`, `Atomics`                                                      | Use them in a step     |

`crypto.randomUUID()` and `crypto.getRandomValues()` still work and stay deterministic. See [`WORKFLOW_VM`](/docs/configuration/runtime-tuning#workflow_vm) for the full list.

## Tuning

Snapshotting needs no configuration. To change how often a run snapshots, set `WORKFLOW_SNAPSHOT_THRESHOLD`. This is the same entry as on the [Runtime tuning](/docs/configuration/runtime-tuning#workflow_snapshot_threshold) page:

### `WORKFLOW_SNAPSHOT_THRESHOLD`

- Default: `1000` when the QuickJS engine is selected
- Values: non-negative integer. `0` disables snapshotting.
- Only used by the QuickJS engine (`WORKFLOW_VM=quickjs`), and only with a World that provides snapshot storage (world-local, world-postgres, and world-vercel do).
- When above `0`, the runtime persists a **VM-memory snapshot** at a suspension once at least this many events have been processed since the last snapshot. Subsequent invocations restore the VM from the snapshot and replay only the events recorded since, instead of re-executing the workflow from the top against the full event log.
- Short-lived runs below the threshold never pay the snapshot cost; long-running or unbounded runs stop scaling their resume cost with total event-log length. `1` snapshots at every qualifying suspension.
- Choosing a value: a restore costs roughly the same regardless of log length (tens of milliseconds to decompress and restore the heap, plus fetching the snapshot), while a full replay grows with the log (tens of milliseconds at a few hundred events, seconds at several thousand). Restoring starts to pay off at a few hundred events, so values in the hundreds suit most long-running workflows. Very low values mostly add snapshot saves to runs that replay quickly anyway.
- Snapshots are an optimization, not a source of truth: the event log remains authoritative, and a missing, corrupt, oversized, or incompatible snapshot automatically falls back to a full replay. Snapshots over 32 MB uncompressed are not saved.
- Set `0` to opt out and always replay the full event log.
- Like `WORKFLOW_VM`, the policy is stamped into the run's `executionContext` at start, so a run keeps the snapshot policy it started with. Runs started with `WORKFLOW_VM=quickjs` are stamped with this value, or the default when unset. Runs without a stamped policy use the handler's value, or the default. `start()` rejects an invalid value. An invalid value on the workflow handler disables snapshotting with a warning.
- Runs stamped with `workflowVm: "quickjs"` and a positive threshold are exempt from the default [per-run event limit](/docs/errors/max-events-exceeded) on the Local and Vercel Worlds.
- A snapshot can only be restored by the exact QuickJS engine build that captured it. On Vercel, runs keep executing on the deployment they started on, so deploys don't affect in-flight snapshots. If your deployment serves in-flight runs from new code (for example, a self-hosted rolling update), an upgrade that changes the embedded engine or the snapshot format makes every in-flight run fall back to a full replay at its next resume, all at once, before re-snapshotting at its next qualifying suspension. Plan for that one-time replay load when upgrading.

What a snapshot contains, and how it is protected:

- A snapshot is the workflow VM's memory: the workflow's code and in-memory state, including step results and hook payloads it holds, and the copy of `process.env` the VM exposes. It is executable state, so write access to snapshot storage is equivalent to running code in the workflow VM.
- Snapshots are compressed and then encrypted with the run's encryption key. The encryption also authenticates the snapshot: on restore, the runtime rejects any snapshot that isn't encrypted with the run's key, or whose stored metadata doesn't match the metadata sealed inside it.
- By default, runs without an encryption key are never snapshotted. Only world-vercel provides run encryption keys. On world-local and world-postgres, set `WORKFLOW_SNAPSHOT_ALLOW_UNENCRYPTED=1` on the workflow handler to snapshot anyway. Those snapshots are stored in plaintext (in `.workflow-data/snapshots/` or the `workflow_snapshots` table) and are not authenticated, so only enable this where snapshot storage is as trusted as your deployment.
- A restored run sees `process.env` as of the current invocation, the same as a full replay.
- Snapshots are deleted after the run reaches a terminal state. world-local and world-postgres have no separate retention for them, so a snapshot of a run that ends without any invocation observing it (for example, one cancelled externally) stays until you remove it.

## On Vercel

Add `WORKFLOW_VM=quickjs` to your project's environment variables, then redeploy. You can add it in two ways:

- **From a run.** When a run fails at the event limit, times out while replaying, or passes 20,000 events, its page in the Workflows observability tab shows an **Optimize Long Runs** button. It adds the variable to Production and prompts you to redeploy.
- **From project settings.** Open **Settings**, then **Environment Variables**, add the variable, and redeploy.

Runs on Vercel keep executing on the deployment they started on, so the redeploy does not affect runs in progress.

For every setting and what a snapshot contains, see [Runtime tuning](/docs/configuration/runtime-tuning#workflow-vm-engine).

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)