Compute
Worker Loader
Load and run dynamic Workers at runtime with the worker_loaders binding, each in its own Node.js process inside an agentOS VM.
Runs on One Node.js process per dynamic Worker in an agentOS VM, never on the host, Workers RPC over Cap'n Web
- Works
get(),load(),fetch(), and RPC, withenvandpropscapabilities andglobalOutbound- Differs
- Each dynamic Worker runs in its own agentOS VM. A load usually takes a prewarmed VM; when none is ready, it boots one, which takes about 0.3 seconds. Compatibility settings and
limitsare ignored. - Missing
getDurableObjectClass(),connect()to a dynamic Worker, Python modules, and tail events from dynamic Workers- Migration
- Not needed Dynamic Workers are code that the Worker loads at runtime.
- Configure
worker_loaders
A Worker Loader runs code that your Worker hands it at runtime, as a dynamic
Worker you call with fetch() or RPC. On OpenOrange, each dynamic Worker runs
in its own agentOS VM.
Quickstart
-
Bind the loader
Add a
worker_loadersbinding towrangler.jsonc.{ "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2026-09-03", "worker_loaders": [{ "binding": "LOADER" }] } -
Write the dynamic Worker
The code is an object of modules.
globalOutbound: nullblocks the dynamic Worker’s ownfetch().const code = { compatibilityDate: "2026-09-03", mainModule: "main.js", modules: { "main.js": `export default { fetch() { return new Response("Hello from a dynamic Worker"); }, };`, }, globalOutbound: null, }; -
Load it and call it
get()keeps one dynamic Worker per name. Call it withfetch()or RPC through its entrypoint.export default { async fetch(request, env): Promise<Response> { const worker = env.LOADER.get("hello", () => code); return worker.getEntrypoint().fetch(request); }, } satisfies ExportedHandler<Env>; -
Run it
Start
orange dev, then request the Worker.orange dev curl localhost:8787 Hello from a dynamic Worker
How it works
- Dynamic Worker code is untrusted, so each dynamic Worker gets its own VM, as it gets its own isolate on Cloudflare. It never runs on the host.
- Orange keeps VMs booted ahead of use, and more after a burst of loads, so a new dynamic Worker only writes its own modules. Each VM runs one dynamic Worker and is never reused.
- A dynamic Worker stops when it is idle or nothing references it. Its VM is disposed, never returned to the pool.
- Your Worker and the dynamic Worker talk Workers RPC, so stubs and bindings
you pass in
envorpropswork across the boundary.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
| Feature | Status | Notes |
|---|---|---|
get(name, getCode) | Supported | One dynamic Worker per name in each binding. |
get(null, getCode) and load(code) | Supported | Each call starts a new dynamic Worker. |
fetch() and RPC through getEntrypoint() | Supported | Stubs, RpcTargets, functions, service bindings, and Durable Object stubs travel by reference. |
env and props | Supported | Same reference passing as RPC. |
globalOutbound | Supported | null makes fetch() reject and connect() throw. A Fetcher receives the dynamic Worker’s fetch() calls. |
| JavaScript, CommonJS, text, data, JSON, and Wasm modules | Supported | Pass Wasm as bytes. Relative, cloudflare:*, and node:* imports resolve as in the parent Worker. |
A node:http server through cloudflare:node | Supported | An Express app serves requests. |
Python modules and compiled WebAssembly.Module values | Not supported | Throw a TypeError. |
getDurableObjectClass() | Not supported | Throws a NotSupportedError. |
connect() on an entrypoint, or through a Fetcher globalOutbound | Not supported | Throws. |
compatibilityDate, compatibilityFlags, allowExperimental, and limits | Partial | Accepted and ignored. The dynamic Worker uses the parent’s compatibility profile. |
tails and streamingTails | Not supported | Accepted. They receive no events. |
Limits
Orange does not copy Cloudflare’s 64 MiB code and 1 MiB env limits.
agentOS’s limits apply:
| What | Limit | What happens over it |
|---|---|---|
| One module file | 16 MiB | The load fails with a RangeError that names the limit. Split the module. |
| All files in the VM | 64 MiB by default | agentOS’s limit. Orange adds no check. |
env | No set limit. In a test with agentOS 0.4.1, 5 MiB worked. | At 10 MiB, the dynamic Worker exited with code 1. |
| Running dynamic Workers, across all Worker Loader bindings | 32. Set ORANGE_WORKER_LOADER_MAX_WORKERS to change it. | A new dynamic Worker stops the least recently used idle one. If none is idle, it waits in line for a slot, first come first served, and its calls wait with it. At 80% of the limit, Orange logs a warning. |
| Time a dynamic Worker waits for a slot | 5 seconds. Set ORANGE_WORKER_LOADER_QUEUE_TIMEOUT_MS to change it, from 1 to 2147483647. | Its calls reject with a WorkerLoaderLimitError whose code is queue_timeout. |
| Dynamic Workers that wait for a slot | 256. Set ORANGE_WORKER_LOADER_MAX_QUEUED to change it; 0 refuses at once. | Its calls reject with a WorkerLoaderLimitError whose code is queue_full. At 80% of the limit, Orange logs a warning. |
| agentOS VMs, counting running Workers, prewarmed VMs, and VMs that boot or stop | ORANGE_WORKER_LOADER_MAX_WORKERS plus ORANGE_WORKER_LOADER_POOL_MAX, 48 by default. Set ORANGE_WORKER_LOADER_MAX_VMS to change it; it must not be less than ORANGE_WORKER_LOADER_MAX_WORKERS. | Prewarmed VMs stop first, and the pool stops refilling. A Worker that needs a new VM waits for one to stop. At 80% of the budget, Orange logs a warning. |
| Idle time before a dynamic Worker stops | 30 seconds. Set ORANGE_WORKER_LOADER_IDLE_TIMEOUT_MS to change it, from 1 to 2147483647. | The dynamic Worker stops and frees its VM. The next call loads it again. A value out of range stops orange dev at startup with a RangeError that names the setting. |
| Prewarmed VMs when no burst is recent | 2 for each network mode by default, from 0 to 64 with ORANGE_WORKER_LOADER_POOL_SIZE | A load that finds the pool empty boots its own VM. |
| Prewarmed VMs after a burst | 16 for each network mode by default, from 0 to 64 with ORANGE_WORKER_LOADER_POOL_MAX. It must not be less than ORANGE_WORKER_LOADER_POOL_SIZE. 0 boots every VM on demand. | The pool stops growing. A value out of range stops orange dev at startup with a RangeError that names the setting. |
| VMs that prewarm at once | 4, across both network modes, while no Worker loads. While Workers load, only as many as keep up with a steady rate of loads. | The other prewarms wait. Loads never wait for this limit. |
Each running dynamic Worker uses about 54 MiB. Each prewarmed VM uses 26 to
54 MiB, depending on the agentOS version. After a burst of 16 or more loads,
a network mode can hold 16 prewarmed VMs, 0.4 to 0.9 GiB, until the idle
timeout passes. Prewarmed VMs do not count toward
ORANGE_WORKER_LOADER_MAX_WORKERS, but they count toward
ORANGE_WORKER_LOADER_MAX_VMS, which bounds the memory of all VMs.
Refusals
- A
WorkerLoaderLimitErroris aRangeErrorwithcode(queue_fullorqueue_timeout),overloaded: true,retryable: true, andretryAfterSeconds: 1, like the overloaded error of a Cloudflare Durable Object.get()andload()never throw it; the Worker’s calls reject with it. - If your Worker does not catch it, the response is
503 Service UnavailablewithRetry-After: 1, not 500. A WebSocket upgrade gets the same 503. On Cloudflare, an uncaught exception is a 500 (error 1101). Cloudflare has no per-runner Worker limit, so it has no such refusal. - A held stub whose Worker was refused asks for a slot again on its next call,
and
get()with the same name callsgetCodeagain. - Under load that stays above what the runner can start, the line stays full:
a Worker that gets a slot has waited close to the queue timeout, and the
rest are refused. Lower
ORANGE_WORKER_LOADER_QUEUE_TIMEOUT_MSto trade refusals for latency, and scale out on the queue wait (see Monitoring). - agentOS bounds the requests in flight to its shared sidecar at 128, and
each running Worker keeps some open. In a test that started 80 Workers at
once with
ORANGE_WORKER_LOADER_MAX_WORKERSat 96, 33 to 38 started; the rest failed with agentOS’sERR_AGENTOS_IN_FLIGHT_REQUEST_LIMIT. When a running Worker’s process fails this way, its call fails with a 500.
Isolation
- Two dynamic Workers share no filesystem, processes, or loopback.
- A dynamic Worker shares no globals, module state,
process.env, orenvwith the parent Worker. - A dynamic Worker cannot reach the host.
node:fssees only its VM, and it cannot connect to host loopback ports, whatever itsglobalOutbound. - A dynamic Worker with the default
globalOutboundgets a VM with network access. WithglobalOutbound: nullor a Fetcher, its VM has no network.
Lifecycle
- Orange prewarms VMs for each network mode after that mode’s first dynamic
Worker loads, so an app without dynamic Workers boots none. A prewarmed VM
has its Node.js process started with Orange’s runtime imported. It has seen
no Worker code or
env. - With an agentOS client that supports
snapshotEntrypoints, each Node.js process boots from a V8 snapshot of Orange’s runtime, built once per agentOS sidecar, instead of importing it. Each process gets its own copy of the runtime’s state. agentOS 0.4.8 lacks the option, so there each process imports the runtime. - A load takes a prewarmed VM, writes its modules, and starts the Worker. If the pool is empty, it takes a VM that is booting and that no other load waits for, or boots its own at once, beside the other loads.
- Each network mode’s pool aims for the most loads seen within one prewarm
time, from
ORANGE_WORKER_LOADER_POOL_SIZEtoORANGE_WORKER_LOADER_POOL_MAX. So the next burst of the same size finds its VMs ready, and a steady stream of loads keeps the pool ahead. - The pool refills at full speed as soon as no dynamic Worker is loading, because a prewarm that runs beside a load slows it. Workers that load at the same time also hold the refill until their first calls finish. One Worker holds the refill back for at most 1 second.
- While Workers keep loading, the pool still refills, with as many prewarms as the rate of loads needs. Only loads that keep arriving count, so a burst does not refill beside its own loads.
- When the idle timeout (
ORANGE_WORKER_LOADER_IDLE_TIMEOUT_MS) passes without a burst as large, the pool shrinks toORANGE_WORKER_LOADER_POOL_SIZEand disposes the other prewarmed VMs. - A VM that fails to prewarm is reported as a background error, and the next
load boots its own VM. The pool tries to prewarm again only after its next
load. Set
ORANGE_WORKER_LOADER_POOL_MAXto0to boot every VM on demand. - If the VM cannot boot,
get()andload()calls fail with the boot error. Orange never falls back to the host. - A dynamic Worker is idle when no call to it is in flight, your Worker holds
no stub or stream that it returned, no body or stream flows between the two
in either direction, and no call from the dynamic Worker to your Worker or
its
envis in flight. A streamed response body keeps it busy until the body ends. Orange never stops a dynamic Worker that is not idle. - Work that the dynamic Worker does on its own, such as
ctx.waitUntil()code that runs while no call or stream is open, does not keep it busy. It can stop when it is idle. - An idle dynamic Worker stops after the idle timeout, or sooner when the limit of running dynamic Workers needs its slot. Its process exits and its VM is disposed.
- A
load()or unnamedget()Worker also stops when it is idle and the garbage collector has collected its stub and every entrypoint. - After a dynamic Worker stops,
get()with its name callsgetCodeagain, as Cloudflare can. A stub or entrypoint that you still hold loads the Worker again on its next call, with fresh module state. - If a dynamic Worker’s process exits, its pending calls reject, and the next
get()with that name loads it again. - A dynamic Worker that fails to start, for example because
getCodethrows, frees its slot at once. Its calls reject with the startup error. - A process that does not exit 5 seconds after Orange stops it is logged, and Orange disposes its VM.
Transport
- The parent and the dynamic Worker talk Workers RPC over Cap’n Web, framed on the dynamic Worker process’s stdin and stdout.
- The dynamic Worker’s own stdout output still reaches the parent’s stdout.
- Reference passing covers
env,props, arguments, and results.
Modules
- Module forms: a string
.jsmodule (ES module),{ js },{ cjs },{ text },{ data },{ json }, and{ wasm }with bytes, as{ wasm: ArrayBuffer }. compatibilityDateandmainModulemust be strings, andmainModulemust name a module inmodules. Invalid code throws aTypeError.load()copies the code before it returns, so later changes to the caller’s buffers do not reach the dynamic Worker, and invalid code throws at once.
The VM runtime
- The agentOS VM runs Node.js 22.
- The VM bundle fills missing Web globals from
node:stream/web,node:buffer,node:crypto, andnode:perf_hooks, buildsCompressionStreamandDecompressionStreamonnode:zlib, addsURLPatternfromurlpattern-polyfill, and setsnavigator. - Any other global that the VM lacks becomes a class that throws when constructed.
- Workerd stream fixes that read Node.js 24 stream internals do not apply in
the VM, and dynamic Workers there use the VM’s own
WebSocketclass. globalOutbound: nullblocks the globalfetch()andcloudflare:socketsconnect(). The VM with no network also blocksnode:netandnode:httpconnections.- The VM is disposed when the dynamic Worker process exits or stops, or
orange devstops. Stoppingorange devstops every dynamic Worker process. - Each VM mounts the VM bundle read-only at
/open-orange/runtime. A write there fails withEROFS. pnpm buildemits the VM bundle todist/runtime/worker-loader-vm/. Without it, the first dynamic Worker fails withOpenOrange cannot find the agentOS Worker Loader bundle. Run `pnpm build`.
Errors
| Call | Error |
|---|---|
getDurableObjectClass() | NotSupportedError: OpenOrange does not support getDurableObjectClass() on dynamic Workers yet. Keep Durable Object state in the parent Worker and call the dynamic Worker through getEntrypoint(). |
connect() on an entrypoint | NotSupportedError: OpenOrange does not support connect() on a dynamic Worker entrypoint. Use fetch() or RPC methods instead. |
connect() through a Fetcher globalOutbound | OpenOrange does not support connect() through a dynamic Worker's globalOutbound fetcher. Use fetch() instead. |
| A VM that cannot boot | OpenOrange cannot boot the agentOS VM for a dynamic Worker: <message>. Dynamic Workers never run on the host. |
| A new dynamic Worker when the limit is reached and none is idle | WorkerLoaderLimitError: OpenOrange cannot start another dynamic Worker: <n> are running, none is idle, and the limit is <limit>. Raise ORANGE_WORKER_LOADER_MAX_WORKERS or let calls finish first. |
| A module file over 16 MiB | RangeError: Dynamic Worker file <name> is <n> bytes. agentOS writes one file into its VM as one message of at most 16777216 bytes (16 MiB). Split the module. |
Deviations
These add to the Compatibility table, the Limits, and the host isolation and unloading in Isolation and Lifecycle.
- A Worker that fails to load is forgotten, so the next
get()with that name callsgetCodeagain. Workerd keeps the failed Worker. - Workerd keeps a
load()Worker while any stub references it. Orange stops an idle one after the idle timeout even then, and the held stub loads it again with fresh module state. - Orange allows dynamic entrypoint stubs and uncalled
ctx.exportsstubs inprops, where workerd throwsDataCloneError. - The
connect()errors areNotSupportedError-style errors.
Conformance
tests/bindings/worker-loader.test.ts drives a real orange dev over HTTP:
fetch and RPC, env and props capabilities, isolation, globalOutbound: null,
name caching, syntax errors, process crashes, module types, a node:http
server and an Express app in a dynamic Worker, and bursts of loads larger than
the VM pool whose Workers each wait in a call for all the others. The VM pool
grows to the last burst and shrinks to its idle size after the idle timeout,
and each Worker gets a fresh VM, isolated from the others and from the
read-only runtime mount, with its own runtime module state and randomness
when its process boots from the agentOS snapshot. A second orange dev with
a limit of 2 and a 1.5-second idle timeout checks that
idle Workers stop and load again, that calls longer than the timeout finish,
that busy Workers fail a new load with WorkerLoaderLimitError, and that more
load() calls than the limit succeed.
Recorded results
Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.
Worker Loader
| Check | Status | Results |
|---|