Skip to content
Compute / Worker Loader

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.

Partial

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, with env and props capabilities and globalOutbound
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 limits are 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

  1. Bind the loader

    Add a worker_loaders binding to wrangler.jsonc.

    {
      "name": "my-worker",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03",
      "worker_loaders": [{ "binding": "LOADER" }]
    }
  2. Write the dynamic Worker

    The code is an object of modules. globalOutbound: null blocks the dynamic Worker’s own fetch().

    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,
    };
  3. Load it and call it

    get() keeps one dynamic Worker per name. Call it with fetch() 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>;
  4. 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 env or props work 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

FeatureStatusNotes
get(name, getCode)SupportedOne dynamic Worker per name in each binding.
get(null, getCode) and load(code)SupportedEach call starts a new dynamic Worker.
fetch() and RPC through getEntrypoint()SupportedStubs, RpcTargets, functions, service bindings, and Durable Object stubs travel by reference.
env and propsSupportedSame reference passing as RPC.
globalOutboundSupportednull makes fetch() reject and connect() throw. A Fetcher receives the dynamic Worker’s fetch() calls.
JavaScript, CommonJS, text, data, JSON, and Wasm modulesSupportedPass Wasm as bytes. Relative, cloudflare:*, and node:* imports resolve as in the parent Worker.
A node:http server through cloudflare:nodeSupportedAn Express app serves requests.
Python modules and compiled WebAssembly.Module valuesNot supportedThrow a TypeError.
getDurableObjectClass()Not supportedThrows a NotSupportedError.
connect() on an entrypoint, or through a Fetcher globalOutboundNot supportedThrows.
compatibilityDate, compatibilityFlags, allowExperimental, and limitsPartialAccepted and ignored. The dynamic Worker uses the parent’s compatibility profile.
tails and streamingTailsNot supportedAccepted. They receive no events.

Limits

Orange does not copy Cloudflare’s 64 MiB code and 1 MiB env limits. agentOS’s limits apply:

WhatLimitWhat happens over it
One module file16 MiBThe load fails with a RangeError that names the limit. Split the module.
All files in the VM64 MiB by defaultagentOS’s limit. Orange adds no check.
envNo 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 bindings32. 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 slot5 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 slot256. 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 stopORANGE_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 stops30 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 recent2 for each network mode by default, from 0 to 64 with ORANGE_WORKER_LOADER_POOL_SIZEA load that finds the pool empty boots its own VM.
Prewarmed VMs after a burst16 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 once4, 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 WorkerLoaderLimitError is a RangeError with code (queue_full or queue_timeout), overloaded: true, retryable: true, and retryAfterSeconds: 1, like the overloaded error of a Cloudflare Durable Object. get() and load() never throw it; the Worker’s calls reject with it.
  • If your Worker does not catch it, the response is 503 Service Unavailable with Retry-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 calls getCode again.
  • 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_MS to 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_WORKERS at 96, 33 to 38 started; the rest failed with agentOS’s ERR_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, or env with the parent Worker.
  • A dynamic Worker cannot reach the host. node:fs sees only its VM, and it cannot connect to host loopback ports, whatever its globalOutbound.
  • A dynamic Worker with the default globalOutbound gets a VM with network access. With globalOutbound: null or 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_SIZE to ORANGE_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 to ORANGE_WORKER_LOADER_POOL_SIZE and 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_MAX to 0 to boot every VM on demand.
  • If the VM cannot boot, get() and load() 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 env is 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 unnamed get() 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 calls getCode again, 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 getCode throws, 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 .js module (ES module), { js }, { cjs }, { text }, { data }, { json }, and { wasm } with bytes, as { wasm: ArrayBuffer }.
  • compatibilityDate and mainModule must be strings, and mainModule must name a module in modules. Invalid code throws a TypeError.
  • 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, and node:perf_hooks, builds CompressionStream and DecompressionStream on node:zlib, adds URLPattern from urlpattern-polyfill, and sets navigator.
  • 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 WebSocket class.
  • globalOutbound: null blocks the global fetch() and cloudflare:sockets connect(). The VM with no network also blocks node:net and node:http connections.
  • The VM is disposed when the dynamic Worker process exits or stops, or orange dev stops. Stopping orange dev stops every dynamic Worker process.
  • Each VM mounts the VM bundle read-only at /open-orange/runtime. A write there fails with EROFS.
  • pnpm build emits the VM bundle to dist/runtime/worker-loader-vm/. Without it, the first dynamic Worker fails with OpenOrange cannot find the agentOS Worker Loader bundle. Run `pnpm build`.

Errors

CallError
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 entrypointNotSupportedError: OpenOrange does not support connect() on a dynamic Worker entrypoint. Use fetch() or RPC methods instead.
connect() through a Fetcher globalOutboundOpenOrange does not support connect() through a dynamic Worker's globalOutbound fetcher. Use fetch() instead.
A VM that cannot bootOpenOrange 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 idleWorkerLoaderLimitError: 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 MiBRangeError: 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 calls getCode again. 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.exports stubs in props, where workerd throws DataCloneError.
  • The connect() errors are NotSupportedError-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