Skip to content
Compute / Workflows

Compute

Workflows

Run Cloudflare Workflows with OpenOrange on Cloudflare's own Workflows engine.

Partial

Runs on Cloudflare's own Workflows engine, copied from @cloudflare/workflows-shared 0.15.1, with one Rivet Actor per instance

Works
create(), get(), every step API, 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 dev renames them
Missing
instance.subscribe(), limits.steps, retention, the vitest-pool-workers test helpers, and an orange workflows command
Migration
Not supported orange migrate does 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

  1. Bind the Workflow

    Add a workflows entry to wrangler.jsonc.

    {
      "name": "my-worker",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03",
      "workflows": [
        { "binding": "MY_WORKFLOW", "name": "my-workflow", "class_name": "MyWorkflow" }
      ]
    }
  2. 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 };
      }
    }
  3. Start it from your Worker

    create() starts an instance, get() finds it again, and sendEvent() delivers the event that step.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>;
  4. Run it

    orange dev shows the Workflow as a Rivet Actor.

    orange dev
      Binding           Resource   Runs on
      env.MY_WORKFLOW   Workflow   Rivet Actor · MyWorkflow

    Start the instance, approve it, and read its status. It is waiting while it sleeps or waits for the event, and complete, 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 dev runs.
  • 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() or step.waitForEvent(). An alarm or sendEvent() 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:

FeatureStatusNotes
create()SupportedAn 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()SupportedBoth forms.
get()SupportedA missing ID throws instance.not_found.
deleteBatch()Supported
instance.status()SupportedAll 8 statuses occur. See Statuses. There is no __LOCAL_DEV_STEP_OUTPUTS field, which only wrangler dev adds.
instance.pause(), resume(), terminate()Supportedterminate() cannot stop a step callback that is already running. See Deviations.
instance.restart()SupportedAlso { from: { name, count, type } }.
instance.delete()Supported
instance.sendEvent()Supported
instance.subscribe()Not supportedThe engine has it, but the binding does not expose it.
step.do()SupportedWith retries, backoff, and timeouts.
step.sleep(), step.sleepUntil(), step.waitForEvent()Supported
Parallel stepsSupportedSteps awaited together, for example with Promise.all(), run at the same time.
A retry delay function, sensitive: "output", rollback handlers, a ReadableStream step outputUntestedThey come with the engine, but no OpenOrange test covers them yet.
limits.steps in the Wrangler configurationNot supportedNot read. Orange has no step limit. Cloudflare stops an instance at 10,000 steps by default.
retention in create()PartialValidated but not applied. An instance stays until you call delete().
vitest-pool-workers test helpersNot supportedintrospectWorkflow() and the instance modifier are not available.
wrangler workflows commandsNot supportedorange 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.

WhatLimitWhat happens over it
create() params and a sendEvent() payloadThey 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 outputStored in one SQLite commit of at most 128 MiBA larger step output errors the instance with Step <name> output is too large to store.
Steps for each instanceNo limitlimits.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 name share instances.
  • A binding with a script_name of another Worker runs the Workflow in that Worker. Run both Workers in one orange 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-shared 0.15.1. This is the engine that wrangler dev runs.
  • The LICENSE file in that folder names the source commit and the license. Each Orange change has an OPEN-ORANGE comment.
  • 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 }):

  1. Orange sends a Durable Object RPC call to the engine object of [workflow name, id]. This is one Rivet Actor of the internal class openorange:workflow-engine.
  2. The engine stores the instance and sets an alarm for now.
  3. The alarm runs MyWorkflow.run(event, step).
  4. The engine keeps step results, sleeps, and events in the actor’s SQLite storage. The earliest timer is the actor’s alarm.
  5. The actor can sleep during step.sleep(), a retry delay, or step.waitForEvent(). The alarm or a sendEvent() starts the run again.
  6. 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 dev runs its engine on the 2024-10-22 compatibility date, so there a custom name becomes Error, and an error that Workflow code throws gets its name in front of its message.
  • create() with an ID that exists throws WorkflowError: (instance.already_exists) Workflow instance with id "<id>" already exists, also when two creates of one ID run at the same time. The wrangler dev of the pinned Wrangler does not reject a duplicate.
  • A NonRetryableError that run() does not catch errors the instance with its own name and message. Orange’s fixed compatibility profile turns on workflows_preserve_non_retryable_error_message. wrangler dev always shows the generic WorkflowFatalError.
  • terminate(), restart(), and delete() 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 with step.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 with TypeError: 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 dev restart

The upstream corpus runs Cloudflare’s workflows-starter template.

  • tests/examples/runnable-examples.test.ts runs the workflows example: retries that succeed on attempt 3, NonRetryableError, a wait timeout, createBatch(), a taken and an invalid ID, a random ID, and pause() and terminate() on a finished instance.
  • tests/bindings/beyond-cloudflare-quotas.test.ts creates an instance with a 155-character ID and a 300-character step name, and a batch of 150.
  • The lifecycle probe runs create, sendEvent(), terminate(), pause() and resume(), and restart() under both Orange and workerd. The scale-units probe 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
  • Pass: example: workflows
  • Pass: lifecycle: Workflows: create, step, status, complete
  • Pass: lifecycle: Workflows: sendEvent releases a waiting instance
  • Pass: lifecycle: Workflows: terminate() ends a waiting instance
  • Pass: lifecycle: Workflows: pause() and resume()
  • Pass: lifecycle: Workflows: restart() runs a finished instance again