Skip to content
Runtime APIs / Cron Triggers

Runtime APIs

Cron Triggers

Run a Worker's scheduled() handler on a cron schedule with OpenOrange, backed by a Rivet Actor.

Drop-in

Runs on Internal Rivet Actor that evaluates the full Cloudflare cron syntax

Works
triggers.crons with Cloudflare's cron syntax, scheduled() with controller.cron, scheduledTime and waitUntil(), and the local trigger routes
Differs
orange dev runs your crons for real. Overlapping runs are skipped, runs have no time limit, and an invalid expression is skipped with a warning.
Missing
Retries of a failed run, so controller.noRetry() has no effect
Migration
Not needed Schedules come from the Wrangler config. Run each cron in one place at a time during the move. Migration guide
Configure
triggers.crons
Checks
1 pass

Cron Triggers run your Worker’s scheduled() handler on a schedule, in UTC. Your triggers.crons and handler run unchanged, and orange dev runs them on their schedule.

Quickstart

  1. Add a schedule

    List your crons under triggers.crons in wrangler.jsonc. This one runs every minute.

    {
      "name": "my-worker",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03",
      "triggers": {
        "crons": ["* * * * *"]
      }
    }
  2. Write the handler

    Export a scheduled() handler. controller.cron tells you which cron fired.

    export default {
      async scheduled(controller, env, ctx) {
        console.log(controller.cron, new Date(controller.scheduledTime));
      },
    };
  3. Run it

    Start orange dev. Its ready block shows each cron’s next run, and a command that runs one now:

    orange dev
    ● Ready in 1.2s
      Local         http://127.0.0.1:8787
      Cron          "* * * * *" next <next minute>
                    Run one now: curl "http://127.0.0.1:8787/cdn-cgi/local/scheduled?cron=*%20*%20*%20*%20*"

    Each minute, scheduled() runs and its log line appears in the orange dev output.

  4. Run one now

    Run the command from the ready block to call scheduled() without waiting.

    curl "http://127.0.0.1:8787/cdn-cgi/local/scheduled?cron=*%20*%20*%20*%20*"
    ok

How it works

  • One Rivet Actor keeps a job for each cron. The jobs survive a restart of orange dev, and a sleeping actor wakes for its next run.
  • When a job is due, the actor calls your scheduled() handler and waits for its ctx.waitUntil() work.
  • A run that throws does not stop later runs. Its error shows in the orange dev output.
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
triggers.cronsSupportedThe standard Wrangler list. No extra setup is needed.
scheduled(controller, env, ctx) on the default exportSupported
scheduled(controller) on a WorkerEntrypoint default exportSupported
controller.cronSupportedThe expression as written in the configuration.
controller.scheduledTimeSupportedThe minute the job was due, in milliseconds.
ctx.waitUntil()SupportedThe work finishes before the run ends.
controller.noRetry()No effectRivet never retries a failed run.
Cloudflare’s cron syntaxSupportedSee Expressions.
/cdn-cgi/local/scheduled and /__scheduledSupportedAs in wrangler dev, under orange dev only. See Run scheduled() by hand.
scheduled() through a service bindingPartialWorks on a binding to this Worker. To another Worker, it rejects. See Multiple Workers.
wrangler triggers deployNot supportedorange triggers deploy prints that the command is not implemented.

Limits

WhatLimitWhat happens over it
Run timeNone. Cloudflare stops a run after 15 minutes of wall time.Orange runs scheduled() until it finishes, with no CPU time limit.
Runs of one cron at a timeOne. Cloudflare can start a run while the previous run of the same cron is still running.Rivet skips the new run and records it as skipped.
A missed tickNot run, like Cloudflare, for example while orange dev was stoppedA tick that a restart delays by less than a minute still runs.

Configuration

Two crons, one every 5 minutes and one at 15:00 UTC on the 1st of each month:

{
  "triggers": {
    "crons": ["*/5 * * * *", "0 15 1 * *"]
  }
}

Expressions

Orange reads every expression with Cloudflare’s rules: the five fields, *, ,, -, /, month and weekday names, L, W, and LW in the day of month, L and # in the day of week, and weekdays from 1 (Sunday) to 7 (Saturday). When both day fields are set, a day matches either one. An expression that does not parse, or never matches a date, prints a warning. Orange skips that cron and runs the others.

  • The warning names the reason, for example Orange skips cron trigger "61 * * * *": Minute value "61" must be 0-59.
  • ? reads as *. A range whose start is after its end wraps around, as in Quartz.
  • An expression listed twice runs once.

The ready block

orange dev runs every cron automatically, in UTC. When the Worker is ready, it prints each cron’s next run and a curl command that runs the first one now:

● Ready in 1.2s
  Local         http://127.0.0.1:8787
  Cron          "59 23 LW * *" next 2026-10-30T23:59:00.000Z
                Run one now: curl "http://127.0.0.1:8787/cdn-cgi/local/scheduled?cron=59%2023%20LW%20*%20*"

With --json, the ready event has a crons array. Each entry has cron, nextRunAt, and triggerUrl.

Scheduling internals

  • One internal Rivet Actor, openorange:cron with key ["cron"], shown as Cron Triggers (Orange), holds one Rivet cron job per expression. The job’s name is the expression as written. In a session with several Workers, the key also names the Worker, so each Worker keeps its own crons. See Multiple Workers.
  • Orange computes each cron’s next matching minute and gives Rivet that one minute as a concrete expression such as 59 23 30 10 *, in UTC. After each run, Orange sets the next minute. Rivet’s own cron parser lacks LW, crosses month edges for W, and numbers weekdays from 0.
  • orange serve and a deployed Worker run the crons too.
  • At startup, each orange dev process makes the jobs match the configuration: it adds new expressions and deletes removed ones. With an external Rivet Engine, as under orange serve, this runs in the background once the Worker serves requests, and retries with backoff until it succeeds. Each failure appears as an error.
  • The actor exists only for Workers that have crons, or that had crons whose jobs it still has to delete.
  • The jobs are stored in the actor’s SQLite storage.
  • When a job is due, the actor calls scheduled() in the process that hosts it.
  • Errors from scheduled() and its waitUntil() promises appear in the orange dev output as errors, and as error events with --json. The actor records the run as failed with scheduled() failed for cron trigger "<expression>", and the next tick still runs.

Turn crons off

ORANGE_CRONS=off runs no cron on this Orange: in .dev.vars for orange dev, or with orange deploy --var ORANGE_CRONS:off. Orange deletes the jobs of the configured crons, as for crons removed from the configuration. Remove the setting to run them again. A migration from Cloudflare uses it, so that each cron runs in one place. See Cron triggers in the migration guide.

Run scheduled() by hand

These routes work like wrangler dev. They run scheduled() in the process that receives the request, and they work with or without triggers.crons.

RouteResponse
/cdn-cgi/local/scheduled?cron=<expression>&time=<ms>ok (200) or exception (500). Add format=json for {"outcome", "noRetry"}.
/__scheduled?cron=<expression>Only with orange dev --test-scheduled. Ran scheduled event (200), or Internal Server Error (500) when the run fails. Without the flag, the Worker’s fetch() gets the request.

A run fails when scheduled() throws, when a waitUntil() promise rejects, or when the Worker has no scheduled() handler. A Worker without one fails with Handler does not export a scheduled() function, and noRetry is true.

orange serve and a deployed Worker do not serve these routes. The request reaches the Worker’s fetch(), so nobody can run a deployed Worker’s crons over HTTP.

curl "http://127.0.0.1:8787/cdn-cgi/local/scheduled?cron=*/5+*+*+*+*"

Deviations

These add to the differences under Limits and the noRetry() row under Compatibility.

  • Orange runs crons in orange dev. Wrangler does not run crons in local development. It only prints the curl command. A project that expects “crons never fire in dev” gets real runs.
  • Invalid expressions. Cloudflare rejects an invalid expression at deploy. orange dev warns and skips only that cron.

Conformance

The generated event registry check verifies that the scheduled execution context has exactly the Cloudflare ExecutionContext keys. Behavior tests in tests/events/cron-triggers.test.ts run real orange dev processes over HTTP. They check that:

  • Each cron runs every minute with its own expression, and a scheduled() that throws does not stop later runs.
  • 59 23 LW * * and 0 0 * * 2/2 are due on the minutes Cloudflare picks, and an invalid expression is skipped with a warning.
  • /cdn-cgi/local/scheduled returns 500 when scheduled() throws or a waitUntil() promise rejects, and 200 otherwise. time and format=json work.
  • /__scheduled returns 500 when scheduled() throws, and 200 otherwise.
  • A tick missed while orange dev was stopped does not run after the restart.
  • A cron removed from the configuration stops after a restart.
  • With ORANGE_CRONS=off, no cron runs, including the jobs that an earlier start left.
  • Two orange dev processes on one Rivet Engine run each tick once.

The runnable example tests/fixtures/examples/cron has five jobs, including Cloudflare-only syntax and a job that always fails. tests/examples/runnable-examples.test.ts runs it end to end.

tests/cli/orange-serve.test.ts checks that orange serve has no local cron route, and that it deletes the jobs of a removed configuration after a restart on an empty disk. workerd’s upstream http-server-nodejs-test testScheduled fails with The RPC receiver does not implement the method "scheduled".

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.

Cron Triggers
Check Status Results
Cron Triggers Works
  • Pass: example: cron