Run background jobs
Make sure the scheduled jobs run on your platform, run a round by hand, and act on the warning /setup shows when they stop.
Fulfilment retries and unfinished AI tasks are handled by a round of scheduled jobs that should run once a minute. On most deployments it already does. This guide confirms that, shows how to run a round yourself, and explains what to do when /setup reports that rounds have stopped. For how the lock and the heartbeat work, see Background jobs.
Before you begin
- A deployed project, or a local one with a migrated database.
- An admin account with
config.readto open/setup. - The platform the project deploys to, from the
platformfield indeploy.config.json. See Deployment model.
Make sure rounds run on your platform
Find your trigger
| Platform | What starts a round | What to check |
|---|---|---|
| Cloudflare | The Worker's Cron Trigger | wrangler.jsonc keeps "triggers": { "crons": ["* * * * *"] } and the deployed Worker lists the trigger |
| Fly.io | A loop inside the web process | fly.toml keeps min_machines_running = 1; a stopped machine runs nothing |
| Railway | A loop inside the web service | The web service is running |
| Docker | A loop inside the web container | The container is up: docker compose ps |
| Local | The same loop, started by the first request to pnpm dev | Open any page once |
On the Node platforms the loop is on unless JOBS_IN_PROCESS=false is set.
Decide whether to use an external cron
Keep the in-process loop unless you have a reason to move scheduling out of the web process, for example web machines that scale to zero. In that case set JOBS_IN_PROCESS=false in the web app's environment and have your scheduler run this once a minute, with the same database variables as the web app:
pnpm jobs:runRunning both the loop and a cron is safe. A lock row lets one runner take each round and the others skip.
Run a round by hand
From a checkout whose .env points at the database you want to act on:
pnpm jobs:runIt prints the round's report and exits non-zero when a job failed:
{
"startedAt": "2026-11-17T08:00:00.000Z",
"finishedAt": "2026-11-17T08:00:00.412Z",
"jobs": [
{ "name": "credit-sweep", "ok": true, "counts": { "expiredUsers": 0, "granted": 0 } },
{ "name": "billing-fulfilments", "ok": true, "counts": { "attempted": 0, "succeeded": 0 } },
{ "name": "ai-channel-tasks", "ok": true, "counts": { "polled": 0 } }
]
}If it prints "skipped", another runner took the round within the last minute. This is expected. Wait a minute and run it again. A project with agent-starter installed has a fourth job, agent-maintenance.
Read the warning on /setup
Open /setup and find the scheduled-jobs item. The page evaluates it from the last recorded round on every load.
| The item says | Meaning | Do |
|---|---|---|
| No scheduled round has been recorded | Nothing has run since the database was created | On a new deployment wait a minute. If it stays, the trigger in the table above is missing |
| The last scheduled round ran N minutes ago | More than five minutes without a round | Check the trigger for your platform; the message names it. Fulfilment retries and AI task polling wait until rounds resume |
| The last round had failures | A job threw | Read the job name and error in the message, fix the cause, then run pnpm jobs:run and read that job's result |
| Last round less than a minute ago, every job succeeded | Rounds are running | Nothing |
A failed job does not stop the other jobs in the round, and it is tried again in the next round.
Verify rounds are running
/setupshows the scheduled-jobs item as ready, with a last round at most a few minutes old.- Reload
/setuptwo minutes later. The time of the last round has advanced. - In
config_settings,jobs.last_run_atholds a recent ISO timestamp andjobs.last_reportthe report of that round. pnpm validate:optional-agentpasses. Before a release,pnpm smoke:node(afterpnpm build:node) orpnpm smoke:worker(afterpnpm build) starts the built app on a throwaway database and checks that a round is recorded.
Next steps
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.
Validators and the release gate
Why every capability carries an executable check that asserts behaviour and wiring, and how the release gate decides which checks must pass.