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.
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, andconnect(), to the same Worker or another Worker of the session- Differs
- Workers reach each other only inside one
orange devororange serve.orange deployships one Worker. - Missing
- WebSocket upgrades,
queue(), andscheduled()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.
Runs on env.DISPATCHER.get(name) finds the user Worker by name among the Workers of the orange dev session
- Works
get(name), andfetch()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 migratedoes not move the user Workers of a dispatch namespace. Run each with another-coption.
- 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.
-
Name and bind the Workers
Every Worker sets
namein itswrangler.jsonc, and bindings find other Workers by it. The gateway bindsauthtwice, the second time on itsAdminentrypoint. 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" }] } -
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 }; } } -
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 -
Run them together
Pass one
-cper 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.jsoncThen call the gateway. An error that
auththrows 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
-coptions toorange 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
| Feature | Status | Notes |
|---|---|---|
Service binding fetch() | Supported | |
| Service binding JS RPC | Partial | Errors keep their type, message, and own properties, and are marked remote. Upstream js-rpc-test passes 28 of 33. |
| Named entrypoints | Partial | Work. The upstream namedServiceBinding test hangs. |
props | Supported | They reach ctx.props. |
connect() | Supported | To this Worker or another Worker of the session. |
| WebSocket upgrade to another Worker | Not supported | Throws. Connect to that Worker’s own URL instead. |
queue() and scheduled() on a binding | Partial | Work on a binding to this Worker. To another Worker, they reject. |
Workers in separate orange dev processes | Not supported | They do not find each other. |
Several Workers in one orange deploy | Not supported | The 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) | Supported | A missing Worker throws Worker not found. |
Dispatch args, limits, and outbound Workers | Not supported | Ignored. |
Limits
| What | Limit | What happens over it |
|---|---|---|
Workers per orange deploy | 1 | It stops with orange deploy supports one Worker for now. Pass a single --config and deploy each Worker on its own. |
Workers with one name | 1 | orange dev stops with open-orange dev received more than one Worker named <name>. |
| Consumers of one queue | 1 in the session | orange 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 name | 1 in the session | orange dev stops at startup with Workflow "<name>" is defined by both <a> and <b>. A Workflow name must be unique. |
* in an orange serve route | Only at the start of the host and the end of the path | orange 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.jsonc | On Orange |
|---|---|
name | Required in every Worker when you pass more than one -c. Bindings find other Workers by it. |
services that names this Worker’s own name | Calls this Worker in process. |
services that names another Worker | Calls 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 entrypoint | Calls that named WorkerEntrypoint export. |
A Durable Object binding with script_name | The object runs in the Worker that exports the class. See Durable Objects. |
A Workflow binding with script_name | Instances run in the Worker that defines the Workflow. See Workflows. |
dispatch_namespaces | Needs no target. namespace is not checked. get(name) finds any Worker of the session. |
tail_consumers | Can name another Worker of the session. See Tail Workers. |
Runtimes and transport
fetch(), RPC, andconnect()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 withscript_nameruns 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 thatname, on its default entrypoint. Pass user Workers with more-coptions.- A Workflow binding with
script_namecreates and reads instances in the Worker that exports the class. A missing Worker throwsWorker "<name>" not found. Make sure it is running locally. - A binding to the Worker’s own
nameruns in process. Withoutnamein 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 isdatabase_id,id, orbucket_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 d1reaches 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
routesmatch 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 servejoin 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 serverequiresnamein 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. Acustom_domainroute matches every path of its host. - With routes, or with
ORANGE_FORWARDED_HOST_SECRETset, 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-hostandx-orange-forwarded-host-signature, an HMAC-SHA256 of the lowercased host with the secret inORANGE_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 answers503with 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()andscheduled()through a binding to another Worker reject with aTypeError:queue() can't reach another Worker of the sessionorscheduled() can't reach another Worker of the session.- Upstream
js-rpc-testfailsdisposal(not implemented),namedServiceBindingandportAbortCall(they hang),sendStubOverRpc, andserializeHttpTypes.
Conformance
tests/bindings/multi-worker.test.tsruns two Workers throughorange devand checks servicefetch(), 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.tschecksconnect()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.tschecks that D1, KV, and R2 are shared by ID, and that a database with another ID stays separate.tests/cli/orange-serve.test.tsruns several Workers onorange servewith a standalone Engine: routing byroutes, calls between the Workers, each Worker’s own cron, a queue across Workers, forwarded hosts, and a refused route.tests/examples/runnable-examples.test.tsrunsexamples/multi-workerend 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 |
|
connect() through a service binding to another Worker | Works |
|
queue() and scheduled() on a service binding | Works |
|
Workers for Platforms (dispatch namespaces)
| Check | Status | Results |
|---|---|---|
| Service bindings and dispatch namespaces | Works |
|