Kernlift

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.read to open /setup.
  • The platform the project deploys to, from the platform field in deploy.config.json. See Deployment model.

Make sure rounds run on your platform

Find your trigger

PlatformWhat starts a roundWhat to check
CloudflareThe Worker's Cron Triggerwrangler.jsonc keeps "triggers": { "crons": ["* * * * *"] } and the deployed Worker lists the trigger
Fly.ioA loop inside the web processfly.toml keeps min_machines_running = 1; a stopped machine runs nothing
RailwayA loop inside the web serviceThe web service is running
DockerA loop inside the web containerThe container is up: docker compose ps
LocalThe same loop, started by the first request to pnpm devOpen 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:run

Running 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:run

It 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 saysMeaningDo
No scheduled round has been recordedNothing has run since the database was createdOn a new deployment wait a minute. If it stays, the trigger in the table above is missing
The last scheduled round ran N minutes agoMore than five minutes without a roundCheck the trigger for your platform; the message names it. Fulfilment retries and AI task polling wait until rounds resume
The last round had failuresA job threwRead 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 succeededRounds are runningNothing

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

  • /setup shows the scheduled-jobs item as ready, with a last round at most a few minutes old.
  • Reload /setup two minutes later. The time of the last round has advanced.
  • In config_settings, jobs.last_run_at holds a recent ISO timestamp and jobs.last_report the report of that round.
  • pnpm validate:optional-agent passes. Before a release, pnpm smoke:node (after pnpm build:node) or pnpm smoke:worker (after pnpm build) starts the built app on a throwaway database and checks that a round is recorded.

Next steps