Compute
Workflows
Run Cloudflare Workflows with OpenOrange on Cloudflare's own Workflows engine.
Runs on Cloudflare's own Workflows engine, copied from @cloudflare/workflows-shared 0.15.1, with one Rivet Actor per instance
- Works
create(),get(), everystepAPI,sendEvent(), pause, resume, terminate, and restart, on Cloudflare's own Workflows engine- Differs
- Rivet's size limits apply instead of Cloudflare's 1 MiB, and errors keep their names where
wrangler devrenames them - Missing
instance.subscribe(),limits.steps,retention, thevitest-pool-workerstest helpers, and anorange workflowscommand- Migration
- Not supported
orange migratedoes not move Workflow instances. Copy the data yourself.
- Configure
workflows- Scales by
- Instance
- Checks
- 1 pass
A Workflow is a job of many steps that survives restarts: each step’s result is saved, and the run can sleep or wait for an event. On OpenOrange, your Workflow code and Wrangler configuration run unchanged, with one Rivet Actor for each instance.
Quickstart
-
Bind the Workflow
Add a
workflowsentry towrangler.jsonc.{ "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2026-09-03", "workflows": [ { "binding": "MY_WORKFLOW", "name": "my-workflow", "class_name": "MyWorkflow" } ] } -
Write the Workflow
Extend
WorkflowEntrypoint, and export the class from your Worker’s entry file. This one charges, sleeps, then waits for an approval event.import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers"; export class MyWorkflow extends WorkflowEntrypoint<Env, { amount: number }> { async run(event: WorkflowEvent<{ amount: number }>, step: WorkflowStep) { const order = await step.do("charge", { retries: { limit: 3, delay: "1 second" } }, async () => { return { charged: event.payload.amount }; }); await step.sleep("cool down", "10 seconds"); const approval = await step.waitForEvent<{ by: string }>("approval", { type: "approved", timeout: "1 hour" }); return { order, approver: approval.payload.by }; } } -
Start it from your Worker
create()starts an instance,get()finds it again, andsendEvent()delivers the event thatstep.waitForEvent()waits for.export default { async fetch(request, env): Promise<Response> { const { pathname } = new URL(request.url); if (pathname === "/start") { await env.MY_WORKFLOW.create({ id: "order-1", params: { amount: 42 } }); } const instance = await env.MY_WORKFLOW.get("order-1"); if (pathname === "/approve") { await instance.sendEvent({ type: "approved", payload: { by: "ada" } }); } return Response.json(await instance.status()); }, } satisfies ExportedHandler<Env>; -
Run it
orange devshows the Workflow as a Rivet Actor.orange dev Binding Resource Runs on env.MY_WORKFLOW Workflow Rivet Actor · MyWorkflowStart the instance, approve it, and read its status. It is
waitingwhile it sleeps or waits for the event, andcomplete, with its output, once both are done.curl localhost:8787/start curl localhost:8787/approve curl localhost:8787/
How it works
- Orange runs Cloudflare’s own Workflows engine, the one
wrangler devruns. - Each instance is one Rivet Actor. Its step results, sleeps, and events live in the actor’s SQLite database.
- The actor sleeps during
step.sleep()orstep.waitForEvent(). An alarm orsendEvent()wakes it, and the run replays: finished steps return their stored results.
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
The engine runs every step API. The binding implements:
| Feature | Status | Notes |
|---|---|---|
create() | Supported | An ID that exists throws. See Deviations. An ID outside ^[a-zA-Z0-9_][a-zA-Z0-9-_]*$ throws WorkflowError: Workflow instance has invalid id. Without an ID, the instance gets a random UUID. |
createBatch() | Supported | Both forms. |
get() | Supported | A missing ID throws instance.not_found. |
deleteBatch() | Supported | |
instance.status() | Supported | All 8 statuses occur. See Statuses. There is no __LOCAL_DEV_STEP_OUTPUTS field, which only wrangler dev adds. |
instance.pause(), resume(), terminate() | Supported | terminate() cannot stop a step callback that is already running. See Deviations. |
instance.restart() | Supported | Also { from: { name, count, type } }. |
instance.delete() | Supported | |
instance.sendEvent() | Supported | |
instance.subscribe() | Not supported | The engine has it, but the binding does not expose it. |
step.do() | Supported | With retries, backoff, and timeouts. |
step.sleep(), step.sleepUntil(), step.waitForEvent() | Supported | |
| Parallel steps | Supported | Steps awaited together, for example with Promise.all(), run at the same time. |
A retry delay function, sensitive: "output", rollback handlers, a ReadableStream step output | Untested | They come with the engine, but no OpenOrange test covers them yet. |
limits.steps in the Wrangler configuration | Not supported | Not read. Orange has no step limit. Cloudflare stops an instance at 10,000 steps by default. |
retention in create() | Partial | Validated but not applied. An instance stays until you call delete(). |
vitest-pool-workers test helpers | Not supported | introspectWorkflow() and the instance modifier are not available. |
wrangler workflows commands | Not supported | orange workflows prints that the command is not implemented, so no command lists or manages instances. |
Limits
Rivet’s limits apply, not Cloudflare’s 1 MiB.
| What | Limit | What happens over it |
|---|---|---|
create() params and a sendEvent() payload | They cross one Durable Object RPC call: at most 32 MiB on the wire. Binary data counts 4/3 of its size. | The call throws a RangeError, and the instance stays as it was. |
| A step output and the instance output | Stored in one SQLite commit of at most 128 MiB | A larger step output errors the instance with Step <name> output is too large to store. |
| Steps for each instance | No limit | limits.steps is not read. |
Workflow names, instance IDs, step names, and instances per createBatch() | No length or count limit. Cloudflare’s 64, 100, and 256 characters and 100 instances per batch are not copied. | The call succeeds. Tested with a 155-character ID, a 300-character step name, and a batch of 150. |
Configuration
OpenOrange reads the standard Wrangler Workflow binding. Export the class from the Worker. No extra setup is needed.
- Bindings with the same
nameshare instances. - A binding with a
script_nameof another Worker runs the Workflow in that Worker. Run both Workers in oneorange dev. See Multiple Workers.
The engine
The engine is Cloudflare’s. Orange did not write its own:
- The code in
packages/runtime-node/src/bindings/workflows/engine/is copied from Cloudflare’s@cloudflare/workflows-shared0.15.1. This is the engine thatwrangler devruns. - The
LICENSEfile in that folder names the source commit and the license. Each Orange change has anOPEN-ORANGEcomment. - The Orange changes connect the engine to Rivet. They keep its storage in the actor, wake it with a Durable Object alarm, and use Rivet’s limits in place of Cloudflare’s quotas.
What happens on create()
When you call env.MY_WORKFLOW.create({ id, params }):
- Orange sends a Durable Object RPC call to the engine object of
[workflow name, id]. This is one Rivet Actor of the internal classopenorange:workflow-engine. - The engine stores the instance and sets an alarm for now.
- The alarm runs
MyWorkflow.run(event, step). - The engine keeps step results, sleeps, and events in the actor’s SQLite storage. The earliest timer is the actor’s alarm.
- The actor can sleep during
step.sleep(), a retry delay, orstep.waitForEvent(). The alarm or asendEvent()starts the run again. - The run replays: completed steps return their stored results, and a sleep waits only for the time that is left.
While a step runs, or while run() runs code between steps, the run keeps its
actor awake. The alarm is then at most 5 seconds away. So if a forced sleep, a
crash, or a restart stops a run in the middle of a step, the run starts again
in about 5 seconds. The step runs again, as Cloudflare retries a step whose
engine stopped.
Statuses
All 8 statuses occur: queued, running, paused, waitingForPause,
waiting, errored, terminated, and complete. Cloudflare’s open engine
never sets waiting, so OpenOrange sets it while every step call in flight is
a sleep or an event wait, as Cloudflare reports it while an instance
hibernates.
Errors
Errors keep their names, as workerd’s RPC keeps them with
enhanced_error_serialization, which Orange’s fixed compatibility profile
turns on. For example, a step that throws a CustomError("boom") errors the
instance with { name: "CustomError", message: "boom" }, and a
waitForEvent() timeout throws a WorkflowTimeoutError.
Deviations
- Errors keep their names.
wrangler devruns its engine on the 2024-10-22 compatibility date, so there a custom name becomesError, and an error that Workflow code throws gets its name in front of its message. create()with an ID that exists throwsWorkflowError: (instance.already_exists) Workflow instance with id "<id>" already exists, also when two creates of one ID run at the same time. Thewrangler devof the pinned Wrangler does not reject a duplicate.- A
NonRetryableErrorthatrun()does not catch errors the instance with its own name and message. Orange’s fixed compatibility profile turns onworkflows_preserve_non_retryable_error_message.wrangler devalways shows the genericWorkflowFatalError. terminate(),restart(), anddelete()cannot stop a step callback that is already running, because the Worker and the engine share one process. Its result is discarded, and the run does not reach its next step.- The actor can sleep while every step call in flight is a sleep or an event
wait. Code that runs at the same time outside steps, for example a
fetch()awaited together withstep.sleep(), can be cut off and runs again on the next replay. - A Durable Object response larger than one tunnel message, such as a
status()with an output of hundreds of KiB, can be cut off under load withTypeError: terminated. This is a RivetKit bug.
Conformance
tests/bindings/workflows.test.ts drives a fixture Worker through orange dev.
The expected values are what the same Worker shows under wrangler dev, apart
from the deviations. It covers:
- Terminate during a step and after the actor sleeps
- Pause during a sleep and during a step, and resume
- Restart from the start, from a step, and during a step
- Parallel steps
- An event sent before its wait, and an event larger than Cloudflare’s 1 MiB
- Wait timeouts
- Two instances with the same step names
- A sleep that ends from the alarm with no requests
- A step longer than the idle sleep timeout
- Failed steps
- Delete and
deleteBatch() - Duplicate and concurrent IDs
- A sleep across an
orange devrestart
The upstream corpus runs Cloudflare’s workflows-starter template.
tests/examples/runnable-examples.test.tsruns theworkflowsexample: retries that succeed on attempt 3,NonRetryableError, a wait timeout,createBatch(), a taken and an invalid ID, a random ID, andpause()andterminate()on a finished instance.tests/bindings/beyond-cloudflare-quotas.test.tscreates an instance with a 155-character ID and a 300-character step name, and a batch of 150.- The
lifecycleprobe runs create,sendEvent(),terminate(),pause()andresume(), andrestart()under both Orange and workerd. Thescale-unitsprobe checks that each instance is one actor.
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.
Workflows
| Check | Status | Results |
|---|---|---|
| Workflows | Works |
|