Runtime APIs
Cron Triggers
Run a Worker's scheduled() handler on a cron schedule with OpenOrange, backed by a Rivet Actor.
Runs on Internal Rivet Actor that evaluates the full Cloudflare cron syntax
- Works
triggers.cronswith Cloudflare's cron syntax,scheduled()withcontroller.cron,scheduledTimeandwaitUntil(), and the local trigger routes- Differs
orange devruns 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
-
Add a schedule
List your crons under
triggers.cronsinwrangler.jsonc. This one runs every minute.{ "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2026-09-03", "triggers": { "crons": ["* * * * *"] } } -
Write the handler
Export a
scheduled()handler.controller.crontells you which cron fired.export default { async scheduled(controller, env, ctx) { console.log(controller.cron, new Date(controller.scheduledTime)); }, }; -
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 theorange devoutput. -
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 itsctx.waitUntil()work. - A run that throws does not stop later runs. Its error shows in the
orange devoutput.
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 |
|---|---|---|
triggers.crons | Supported | The standard Wrangler list. No extra setup is needed. |
scheduled(controller, env, ctx) on the default export | Supported | |
scheduled(controller) on a WorkerEntrypoint default export | Supported | |
controller.cron | Supported | The expression as written in the configuration. |
controller.scheduledTime | Supported | The minute the job was due, in milliseconds. |
ctx.waitUntil() | Supported | The work finishes before the run ends. |
controller.noRetry() | No effect | Rivet never retries a failed run. |
| Cloudflare’s cron syntax | Supported | See Expressions. |
/cdn-cgi/local/scheduled and /__scheduled | Supported | As in wrangler dev, under orange dev only. See Run scheduled() by hand. |
scheduled() through a service binding | Partial | Works on a binding to this Worker. To another Worker, it rejects. See Multiple Workers. |
wrangler triggers deploy | Not supported | orange triggers deploy prints that the command is not implemented. |
Limits
| What | Limit | What happens over it |
|---|---|---|
| Run time | None. 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 time | One. 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 tick | Not run, like Cloudflare, for example while orange dev was stopped | A 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:cronwith key["cron"], shown asCron 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 lacksLW, crosses month edges forW, and numbers weekdays from 0. orange serveand a deployed Worker run the crons too.- At startup, each
orange devprocess makes the jobs match the configuration: it adds new expressions and deletes removed ones. With an external Rivet Engine, as underorange 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 itswaitUntil()promises appear in theorange devoutput as errors, and aserrorevents with--json. The actor records the run as failed withscheduled() 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.
| Route | Response |
|---|---|
/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 thecurlcommand. A project that expects “crons never fire in dev” gets real runs. - Invalid expressions. Cloudflare rejects an invalid expression at deploy.
orange devwarns 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 * *and0 0 * * 2/2are due on the minutes Cloudflare picks, and an invalid expression is skipped with a warning./cdn-cgi/local/scheduledreturns 500 whenscheduled()throws or awaitUntil()promise rejects, and 200 otherwise.timeandformat=jsonwork./__scheduledreturns 500 whenscheduled()throws, and 200 otherwise.- A tick missed while
orange devwas 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 devprocesses 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 |
|