Scaling Dimensions
Single-Server Scaling
Worker Pool
By default a script runs on the thread that calledrun(). To run scripts on several threads, use the worker pool adapter:
globals are not available in a worker. See Worker Pool.
Pool Sizing Guidelines
maxWorkers wait in the pool’s queue, and the wait counts against the script’s timeout. A full queue fails the execution with QueueFullError, a wait longer than queueTimeoutMs with QueueTimeoutError.
Enclave Pooling
AnEnclave can be reused for many executions, and with the worker pool one enclave already runs several scripts at a time. To bound the number of in-process executions yourself, keep a pool of enclaves:
Scaling Out
Architecture
The EnclaveJS broker runs the sandbox in its own process, and a session lives in the memory of the broker that created it. To scale out, run several brokers behind a load balancer:There is no shared session store and no separate runtime tier in the packages.
@enclave-vm/broker has no Redis or routing options, and @enclave-vm/runtime holds building blocks of a runtime worker but does not execute scripts: an execute request ends with RuntimeNotImplementedError.Broker Configuration
sessions.maxSessions sessions are registered, a further POST /sessions is answered with 503 MAX_SESSIONS_REACHED: use that as the backpressure signal.
A session runs on the broker’s thread. A script that computes without calling a tool holds that thread, and every other session of that broker, until it ends or reaches toolTimeoutMs. Keep the limit low, or give the sandbox the worker pool (enclave: { adapter: 'worker_threads' }).
Client Configuration
Kubernetes Scaling
Horizontal Pod Autoscaler
Pod Disruption Budget
Resource Quotas
memoryLimit is an estimate, and a worker’s heap limit is a backstop: the container’s limit is what bounds a pod.
Load Balancing
Sticky Sessions
A session’s later requests (a reconnect toGET /sessions/:sessionId/stream, a cancel, a status request) have to reach the broker that holds the session. Another broker answers them with 404. Use session affinity:
- A server-side
EnclaveClientwith the defaultfetchkeeps no cookies. - A browser client on another origin than the broker.
EnclaveClientcallsfetchwithoutcredentials, so the browser neither stores nor sends a cookie of another origin, and the broker’s routes do not answer withAccess-Control-Allow-Credentials, which a request with credentials would need.
headers (for a page on another origin, name that header in the session handler’s allowedHeaders).
Performance
Measure with your own scripts and tools: throughput depends on what a script does and on how long its tools take. As a baseline, a small script that makes one tool call costs about 5.9 ms per execution with the double VM on Node.js 24 and 2.7 ms on Node.js 22 (2.9 ms and 1.6 ms with the single VM), measured on arm64. See the runtime notes in the@enclave-vm/core README for what the numbers depend on.
Monitoring at Scale
Key Metrics
WorkerPoolAdapter.getMetrics(): queuedRequests, executingSlots, timeoutExecutions, memoryKills, maxWorkerMemory, …) and publish them; see Monitoring Worker Health.
Alerting Rules
Best Practices
- Start simple - Use the worker pool before adding servers
- Monitor queue depth - Scale based on pending executions
- Set memory limits - On the sandbox, on the workers and on the container
- Use connection pooling - Reuse the connections your tools need
- Implement backpressure - Reject requests when overloaded (
maxQueueSize,sessions.maxSessions) - Route a session to its broker - Session affinity for reconnects and cancels
- Graceful degradation - Fallback when components fail
Related
- Production Deployment - Deployment guide
- Worker Pool - Worker pool details
- EnclaveJS Broker - Broker configuration