Background jobs
How the web app runs its own periodic work once a minute on every platform, why one lock row is enough, and how /setup detects when it stopped.
The web app has work that no request triggers: retrying a failed fulfilment, finishing an AI task
nobody is polling. That work is in one function, runScheduledJobs(), which runs one round of every job.
Platforms differ only in what calls it. To check your own deployment, see
Run background jobs.
One round, a fixed list of jobs
A round runs the jobs in order. A job that throws is recorded as failed and the next one still runs.
| Job | Does |
|---|---|
credit-sweep | An extension point. The template's ledger has nothing to expire or top up, so it reports zero; a project that adds expiring credits implements it here |
billing-fulfilments | Retries fulfilments that failed when an order was paid or refunded, with backoff |
ai-channel-tasks | Advances asynchronous provider tasks nobody is polling, so they finish and settle credits |
agent-maintenance | With agent-starter only: gives a Cloudflare agent container with unfinished runs one maintenance round. Does nothing for an agent service reached by URL |
These jobs belong to the web app, not to the Agent service. A deployment without the agent runs every
one of them except agent-maintenance, and the agent service's own loop runs none of them.
Three ways a round starts
| Deployment | Trigger | Switch |
|---|---|---|
Node server (Fly.io, Railway, Docker, a VPS, pnpm dev) | A loop inside the web process: first round five seconds after start, then one every minute | JOBS_IN_PROCESS, on by default |
| Cloudflare Worker | The Cron Trigger "crons": ["* * * * *"] in wrangler.jsonc, handled by scheduled in the Worker entry | The triggers block |
| Any | pnpm jobs:run from a system cron, a Kubernetes CronJob or a platform scheduler | Your scheduler |
The Node build starts the loop when the server process loads, so a fresh deployment with no traffic
still retries fulfilments. pnpm dev does not evaluate the server entry, so there the loop starts
with the first request. A Worker is not a long-running process and may not hold a timer, so the loop
never starts there. Setting JOBS_IN_PROCESS=false turns the loop off and leaves scheduling to
pnpm jobs:run.
One lock row keeps it to one round a minute
Triggers are allowed to overlap: every replica runs the loop, and a cron may fire next to it. The lock
is a single row in config_settings, jobs.next_run_at, holding an ISO timestamp.
- A runner claims the round with a conditional update: move
jobs.next_run_atforward only if it is not in the future. Exactly one caller's update changes the row. The others see zero rows updated and return"skipped". - The claim pushes the timestamp five minutes ahead. If the runner dies mid-round, the lock expires after that.
- When the round ends,
jobs.next_run_atis set to one minute after the round started,jobs.last_run_atto the finish time andjobs.last_reportto the round's JSON report.
The comparison is a string comparison of ISO timestamps, which orders the same way on SQLite, D1 and Postgres, and the claim is one statement, so it needs no transaction.
The heartbeat on /setup
/setup stores no status flag for jobs. It reads jobs.last_run_at and jobs.last_report
each time and evaluates them:
| State | /setup shows |
|---|---|
| No round recorded | Not ready. A new deployment records its first round within a minute; if the message stays, nothing is starting them |
| Last round more than five minutes ago | Not ready, with how long ago it ran |
| Last round had a failed job | Not ready, with each failed job's name and error |
| Last round recent and clean | Ready |
Every message ends with how rounds are started on the platform in deploy.config.json: the Cron
Trigger on Cloudflare, min_machines_running = 1 on Fly.io, the web service on Railway, the web
container on Docker. The item has no admin page to link to, because it is fixed in the platform.
Files
pnpm validate:optional-agent runs rounds against the configured database and asserts the lock: a
second call inside the minute skips, two concurrent calls run one round, and a crashed runner's lock
is taken over.