Skip to content
Compute / Multiple Workers

Compute

Multiple Workers

Run several Workers in one orange dev or orange serve, so service bindings, dispatch namespaces, and cross-Worker Durable Objects reach each other by name.

Service bindings let a Worker call another Worker’s fetch() or its methods.

Partial

Runs on One runtime process per Worker in one orange dev session (orange dev -c a.jsonc -c b.jsonc), with fetch() and RPC over loopback HTTP

Works
fetch(), JS RPC, named entrypoints, props, and connect(), to the same Worker or another Worker of the session
Differs
Workers reach each other only inside one orange dev or orange serve. orange deploy ships one Worker.
Missing
WebSocket upgrades, queue(), and scheduled() through a binding to another Worker
Migration
Not needed A service binding holds no data.
Configure
services
Checks
3 pass

Dispatch namespaces let a Worker pick another Worker by name at runtime.

Partial

Runs on env.DISPATCHER.get(name) finds the user Worker by name among the Workers of the orange dev session

Works
get(name), and fetch() on the user Worker that it returns
Differs
The user Workers are the other Workers that you pass with -c. Orange does not check that they belong to the namespace.
Missing
args, limits, and outbound Workers, which have no effect
Migration
Not supported orange migrate does not move the user Workers of a dispatch namespace. Run each with another -c option.
Configure
dispatch_namespaces
Checks
1 pass

Run all your Workers in one orange dev, with one -c per Worker. They reach each other by name, as on one Cloudflare account.

Quickstart

This runs examples/multi-worker: a gateway Worker that calls an auth Worker and a jobs Worker.

  1. Name and bind the Workers

    Every Worker sets name in its wrangler.jsonc, and bindings find other Workers by it. The gateway binds auth twice, the second time on its Admin entrypoint. A dispatch namespace needs no target.

    // wrangler.jsonc, the gateway
    {
      "name": "gateway",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03",
      "services": [
        { "binding": "AUTH", "service": "auth" },
        { "binding": "ADMIN", "service": "auth", "entrypoint": "Admin" }
      ],
      "dispatch_namespaces": [{ "binding": "WORKERS", "namespace": "session-workers" }]
    }
  2. Export an entrypoint

    The other Worker exports a WorkerEntrypoint. You call its methods over JS RPC.

    // auth/src/index.ts, in part
    import { WorkerEntrypoint } from "cloudflare:workers";
    
    export default class Auth extends WorkerEntrypoint<Env> {
      async fetch(request: Request): Promise<Response> {
        const { pathname } = new URL(request.url);
        if (pathname === "/health") return new Response("auth is up");
        return new Response(`auth has no route ${pathname}`, { status: 404 });
      }
    
      async login(user: string): Promise<{ logins: number; user: string }> {
        checkUser(user); // throws a RangeError unless user is lowercase letters
        const logins = await this.env.SESSIONS.getByName(user).login();
        await this.env.USERS.put(user, String(Date.now()));
        return { logins, user };
      }
    }
  3. Call it

    Call the binding like a local object.

    // src/index.ts in the gateway, simplified
    await env.AUTH.fetch("http://auth/health");  // fetch()
    await env.AUTH.login(name);                  // JS RPC
    await env.ADMIN.stats();                     // a named entrypoint
    await env.WORKERS.get("jobs").fetch(request); // a dispatch namespace
  4. Run them together

    Pass one -c per Worker. The first one is the primary Worker, and only it serves the port.

    orange dev -c wrangler.jsonc -c auth/wrangler.jsonc -c jobs/wrangler.jsonc

    Then call the gateway. An error that auth throws arrives with its message.

    curl localhost:8787/health
    auth is up
    curl localhost:8787/login/ada
    {"logins":1,"user":"ada"}
    curl localhost:8787/login/Ada%21
    {"error":"user must be lowercase letters"}

How it works

  • Each Worker runs in its own runtime process. All of them share one Rivet Engine and keep their data in the primary Worker’s .open-orange/ directory.
  • Queues and Workflows are shared by name, and D1, KV, R2, and rate limiters by ID, as across a Cloudflare account.
  • To serve the Workers in production, pass the same -c options to orange serve.
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
Service binding fetch()Supported
Service binding JS RPCPartialErrors keep their type, message, and own properties, and are marked remote. Upstream js-rpc-test passes 28 of 33.
Named entrypointsPartialWork. The upstream namedServiceBinding test hangs.
propsSupportedThey reach ctx.props.
connect()SupportedTo this Worker or another Worker of the session.
WebSocket upgrade to another WorkerNot supportedThrows. Connect to that Worker’s own URL instead.
queue() and scheduled() on a bindingPartialWork on a binding to this Worker. To another Worker, they reject.
Workers in separate orange dev processesNot supportedThey do not find each other.
Several Workers in one orange deployNot supportedThe difference most projects hit: orange deploy ships one Worker, so on a runner pool a binding to another Worker has nothing to reach. To deploy Workers that call each other, see Several Workers in one deployment.
Dispatch namespace get(name)SupportedA missing Worker throws Worker not found.
Dispatch args, limits, and outbound WorkersNot supportedIgnored.

Limits

WhatLimitWhat happens over it
Workers per orange deploy1It stops with orange deploy supports one Worker for now. Pass a single --config and deploy each Worker on its own.
Workers with one name1orange dev stops with open-orange dev received more than one Worker named <name>.
Consumers of one queue1 in the sessionorange dev stops at startup with Queue "<name>" has a consumer in both <a> and <b>. A queue can have only one consumer.
Workers that define one Workflow name1 in the sessionorange dev stops at startup with Workflow "<name>" is defined by both <a> and <b>. A Workflow name must be unique.
* in an orange serve routeOnly at the start of the host and the end of the pathorange serve refuses the route at startup with Route "<pattern>" is not valid. A route may use * only at the start of its host and the end of its path.

What Orange reads

In wrangler.jsoncOn Orange
nameRequired in every Worker when you pass more than one -c. Bindings find other Workers by it.
services that names this Worker’s own nameCalls this Worker in process.
services that names another WorkerCalls that Worker of the session. A Worker that is not running answers fetch() with 503 and Worker "<name>" not found. Make sure it is running locally. RPC throws the same message.
services with entrypointCalls that named WorkerEntrypoint export.
A Durable Object binding with script_nameThe object runs in the Worker that exports the class. See Durable Objects.
A Workflow binding with script_nameInstances run in the Worker that defines the Workflow. See Workflows.
dispatch_namespacesNeeds no target. namespace is not checked. get(name) finds any Worker of the session.
tail_consumersCan name another Worker of the session. See Tail Workers.

Runtimes and transport

  • fetch(), RPC, and connect() to another Worker go over loopback HTTP to that Worker’s runtime.
  • Under orange dev, each Worker serves its actors from its own envoy pool, so a Durable Object with script_name runs in the Worker that exports its class.
  • JS RPC to another Worker uses the same transport as Durable Object RPC. Unlike a Durable Object stub, a failed call does not break the service stub.
  • connect() to another Worker opens a raw tunnel to the callee’s handler, so TCP half-close and backpressure carry over. In a Durable Object, the call waits on the output gate.
  • env.DISPATCHER.get(name) returns a Fetcher for the session Worker with that name, on its default entrypoint. Pass user Workers with more -c options.
  • A Workflow binding with script_name creates and reads instances in the Worker that exports the class. A missing Worker throws Worker "<name>" not found. Make sure it is running locally.
  • A binding to the Worker’s own name runs in process. Without name in the configuration, Orange treats every service binding as a binding to another Worker, so a binding to the Worker itself is not found.

Shared state

State is shared across the session as across a Cloudflare account:

  • Queues and Workflows are shared by name. A message that any Worker sends goes to the Worker that declares the consumer.
  • D1 databases, KV namespaces, R2 buckets, and rate limiters are shared by ID, as in a multi-Worker wrangler dev, so a Worker reads what another Worker wrote. The ID is database_id, id, or bucket_name, and the binding name when the config has none.
  • Each Worker keeps its own cron triggers. Orange adds the Worker name to the cron actor key. A Worker that runs alone keeps its old key, so its local data stays.
  • orange d1 reaches the session’s databases only with the primary Worker’s configuration, the first -c. With another Worker’s configuration it opens a separate, empty database.

Several Workers in one deployment

orange serve takes -c more than once, as orange dev does. It runs every Worker in one deployment, each in its own runtime, and the Workers reach each other as in orange dev.

orange serve -c app/wrangler.json -c api/wrangler.json -c jobs/wrangler.json
  • The serve port answers with the Worker whose routes match the request’s host and path. A request that no route matches goes to the first Worker.
  • When one Worker exits, the deployment stops, so the cluster starts it again.

Routing on orange serve

  • All runtimes of one orange serve join the cluster’s one envoy pool, because a cluster’s Engine accepts only the pools its operator created. The Engine sends an actor only to an envoy that serves the actor’s name, and each Worker’s actors have their own names.
  • orange serve requires name in every configuration and refuses two Workers with one name.
  • The most specific route pattern wins: an exact host before a *. host, then the longer host, then the longer path, then an exact path before a * path. A custom_domain route matches every path of its host.
  • With routes, or with ORANGE_FORWARDED_HOST_SECRET set, a front listens on the serve port and every runtime listens on loopback. Without either, the first Worker’s runtime serves the port.
  • A cluster has one hostname. To serve another host through it, a forwarder in front of the cluster sends x-orange-forwarded-host and x-orange-forwarded-host-signature, an HMAC-SHA256 of the lowercased host with the secret in ORANGE_FORWARDED_HOST_SECRET. With a matching signature, the request is routed and seen as that host. Without the secret or with another signature, the headers are ignored. A Worker never sees either header.
  • Only the first Worker’s runtime serves RIVETKIT_METRICS_PORT, so the cluster’s metrics cover that Worker’s actors only.

Workers that are not running

Orange follows Wrangler’s dev registry, as the service binding row of What Orange reads shows. Also:

  • fetch() on a Durable Object stub answers 503 with the same message.
  • A dispatch namespace call throws Worker not found. Worker "<name>" is not running in this orange dev session. The message starts like Cloudflare’s.

Deviations

These add to the Compatibility table.

  • A WebSocket upgrade through a service binding to another Worker throws OpenOrange does not yet forward WebSocket upgrades through a service binding to Worker "<name>". Connect to that Worker's own URL instead.
  • queue() and scheduled() through a binding to another Worker reject with a TypeError: queue() can't reach another Worker of the session or scheduled() can't reach another Worker of the session.
  • Upstream js-rpc-test fails disposal (not implemented), namedServiceBinding and portAbortCall (they hang), sendStubOverRpc, and serializeHttpTypes.

Conformance

  • tests/bindings/multi-worker.test.ts runs two Workers through orange dev and checks service fetch(), RPC, error types, shared Durable Object state, and missing Workers. It also checks that each Worker gets its own cron ticks, that a queue that one Worker produces to reaches the consumer in the other, and that two consumers for one queue fail at startup.
  • tests/rpc-and-websockets/session-connect.test.ts checks connect() to another Worker, overlapping connections, and a callee with no handler, a handler that throws, or a Worker that is not running.
  • tests/rpc-and-websockets/session-shared-storage.test.ts checks that D1, KV, and R2 are shared by ID, and that a database with another ID stays separate.
  • tests/cli/orange-serve.test.ts runs several Workers on orange serve with a standalone Engine: routing by routes, calls between the Workers, each Worker’s own cron, a queue across Workers, forwarded hosts, and a refused route.
  • tests/examples/runnable-examples.test.ts runs examples/multi-worker end to end.
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.

Service bindings to other Workers
Check Status Results
Service bindings and dispatch namespaces Works
  • Pass: example: multi-worker
  • Pass: example: rpc-entrypoints
connect() through a service binding to another Worker Works
  • Pass: api-tests--connect-handler-test > localAddressViaServiceBinding
queue() and scheduled() on a service binding Works
  • Pass 6/6: api-tests--deserialize-hardening-test
  • Pass: api-tests--queue-metadata-test > queue-metadata-test
Workers for Platforms (dispatch namespaces)
Check Status Results
Service bindings and dispatch namespaces Works
  • Pass: example: multi-worker
  • Pass: example: rpc-entrypoints