Basic Usage
Worker Pool Features
- Pool management - Auto-scaling with min/max workers
- Heap limit - A worker that exceeds
memoryLimitPerWorkeris terminated and replaced: by the engine, or by the pool when the process runs with--max-old-space-size(see The heap limit) - Memory monitoring - A worker that holds more than its limit allows (its own heap and external memory, not the size of the process) is recycled
- Hard halt - A script that is still running five seconds after its
timeoutis terminated with its worker - Rate and size limits - The messages a worker may send per second while it runs one execution, and the size of one message
- The same sandbox - The double VM runs inside the worker; tool calls go through the host’s tool bridge
- Untrusted workers - The host checks every message from a worker against the protocol schema
- A clean worker for every execution - A worker goes back into the pool only when it has confirmed that nothing of the last script is left in it (see How an Execution Ends)
Worker Pool Presets
Using Presets
The pool takes the preset of the enclave’ssecurityLevel; workerPoolConfig overrides single settings of it. The presets are exported as WORKER_POOL_PRESETS.
Configuration Options
maxMessagesPerSecond is counted per execution: what an earlier execution sent from the same worker is not held against the next one. The result of an execution and the worker’s confirmation that it is idle are not counted.
maxMessageSizeBytes is applied before a message is parsed. The limit an execution gets is never below what the enclave’s own limits let one message carry: a tool request (toolBridge.maxPayloadBytes) or a result (memoryLimit). So it decides where those are larger than it, or off: with memoryLimit: 0 it is the only bound on the size of a result.
How an Execution Ends
A worker runs one execution at a time. When the script has returned, the worker sends its result and then confirms that it is idle, which it can only do when nothing of the script keeps its thread busy. The pool hands a worker to the next execution only after that confirmation. A worker that does not confirm within one second is terminated and replaced; the result it sent stands. In every case where the pool ends an execution itself, it ends the worker with it and starts a new one.run() then returns a failure with error.code EXECUTION_ERROR and one of these in error.name:
A worker that the engine ends at its heap limit fails its execution with the engine’s own out-of-memory error for the worker.
enclave.dispose() ends the executions that are in flight with ExecutionAbortedError and terminates every worker, so a disposed pool leaves nothing running.
What a Worker Adds
- Separate V8 heap - Each worker has its own heap, with its own limit (
resourceLimits) - Memory limit - A script that outgrows the limit loses its worker, and the pool goes on with a new one
- Hard stop -
worker.terminate()ends a script that nothing else can interrupt - Recovery - A worker that is terminated or dies is removed from the pool and replaced
The heap limit
memoryLimitPerWorker limits the worker’s old generation. The engine allows the young generation on top of it, which the pool sets to 24 MB, so the most a worker can hold is the sum of the two.
- A heap flag on the process replaces it. When the host process runs with
--max-old-space-size(on the command line or inNODE_OPTIONS), that value becomes the heap limit of every worker thread, whatever limit a worker was created with. The pool reads the actual limit of each new worker. When the engine does not apply the configured one, it logs a warning once and enforces the limit itself: it reads the worker’s heap every 100 ms while the worker executes and terminates it past its limit (WorkerMemoryError). This is approximate, and it needs Node.js 22.16 or later; on an older 22.x the pool can only warn that the limit is not enforced. - Memory outside the heap counts while a worker executes. The engine’s limit covers the heap. On Node.js 22.16 or later the pool also reads, every 100 ms, what the worker holds in its heap and in external memory together, and ends the execution with
WorkerMemoryErrorwhen that is more than the worker’s budget (the limit plus the young generation). The read needs no answer from the worker, so a script that keeps its thread busy does not delay it. - It is not a guarantee that the host process survives. A worker thread shares the process, and Node.js states that a process may still abort with these limits set: an allocation burst that outruns the engine’s shutdown of the worker is a fatal out-of-memory error for the whole process. Inside the sandbox, with the worker’s limit in effect, this has not been observed, and by default the sandbox’s own
memoryLimitstops a script long before the worker’s limit. A host that must survive whatever a script allocates runs the enclave in a child process or a container with a memory limit of the operating system.
What Is Different From In-Process Execution
- Custom globals reach a worker as JSON data. Functions in
globalsare not available there. - Tool names must start with a letter and contain only letters, digits,
:,.,_and-. A call with another name fails with an error the script can catch. - Console output without a
consoleHandleris printed by the host with a[Worker]prefix. toolBridge.mode: 'direct'does not apply: tool requests and responses cross as strings.
When to Use Worker Pool
Use the worker pool adapter when:- Running code from completely untrusted sources
- You need a script to be stopped even if it cannot be interrupted
- A heap limit per worker is wanted as a backstop behind the sandbox’s own
memoryLimit - Processing many concurrent executions
- You need lower latency
- Running trusted or semi-trusted code
- Simpler deployment is preferred
Layers
The script runs in the double VM, inside a worker thread:- Worker Thread - Heap limit, hard stop
- Double VM - The sandbox: allowed globals only, membrane, tool gate, limits
maxSanitizeDepth and maxSanitizeProperties limits, '[Circular]', BigInt to string, Map to object, Set to array), and the values JSON cannot carry (Date, NaN, Infinity, undefined) are sent alongside it and restored, so a Date comes back as a Date.
Monitoring Worker Health
The pool has no callbacks. It keeps counters, which you read from the pool object, so create the pool yourself and hand it to the enclave as its adapter:memoryKills counts every worker that was ended at its memory limit: by the engine, by the pool’s own heap check, or by the memory monitor.
A pool created this way runs each script in the double VM, like adapter: 'worker_threads' with default options; its third constructor argument takes a doubleVm configuration.
Related
- Security Levels - Security presets
- Double VM - Additional security layer
- Configuration - All configuration options