For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/modules/schedules.md (or send Accept: text/markdown).
Scheduled tasks
Recurring workspace work through the schedule actions.
Beginner walkthrough
Prerequisites: Read the two beginner guides below, finish Web local setup, and open this monorepo at its root in your editor. Web settings belong in apps/web/.env.local; Next.js does not read the root .env. /dashboard in the default fake mode is a no-database demo; /auth needs a migrated database.
Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.
1. Open Settings → Developers and use the Schedules controls to create a test job with a UTC run time.
2. Keep the app running and make the same server-only SCHEDULER_TICK_SECRET available to the app and terminal; run the command below from the repository root.
3. Confirm the due time advances and the job reaches its own status. If nothing runs, check the UTC time, scheduler provider, and server logs; never paste the secret into chat.
For custom code, start with the supplied prompts/README.md and copy the closest prompt: prompts/new-app-screen.md for an app screen or prompts/new-landing-page.md for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read AGENTS.md, .ai/PROJECT_CONTEXT.md, and matching .ai/ mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret.
corepack pnpm jobs:tickStore recurring work in the database
Settings scheduling stores the job type and cron rule in workspace-scoped job_schedule rows. Cron fields are evaluated in UTC. createDrizzleJobScheduler.claimDueSchedules claims due rows using FOR UPDATE SKIP LOCKED, advances their next run, then dispatches handlers.
The generic JobRunner promises enqueue/status/cancel. Recurrence belongs to scheduler rows; Trigger.dev workflow semantics stay explicit.
Drive scheduler ticks
Set a server-only SCHEDULER_TICK_SECRET to enable POST /api/internal/scheduler-tick. corepack pnpm jobs:tick calls it for dev/CI; absent configuration returns 404. Under JOB_PROVIDER=trigger, the deployed scheduler.tick cron drives the scheduler.
# Against a running local app, with SCHEDULER_TICK_SECRET configured:
corepack pnpm jobs:tickVerify claims and execution separately
Test overlapping ticks, due/not-due rules, disabled rows, handler failure, cancellation and another workspace's schedule. Inspect claim/advance and job completion separately; a claimed row is not proof of completed work.
Setup and configuration
Scheduled work — digests, cleanups, renewals — goes through schedule-actions rather than ad-hoc timers: listWorkspaceSchedules, upsertScheduleAction, and removeScheduleAction manage a workspace's cron-driven tasks.
A schedule names the task, the cron expression, and the workspace it runs under. The worker resolves context at run time, so a paused or deleted schedule stops producing work without a redeploy.
listWorkspaceSchedules()
upsertScheduleAction({ task, cron })
removeScheduleAction(formData)Implementation workflow
Treat every scheduled run as untrusted input: re-resolve the workspace and entitlement inside the run, because state may have changed since registration. Make the task idempotent — a retried or doubly-fired run must not duplicate effects.
Schedules are operational surface: keep them visible in settings or logs so a stuck or runaway schedule is found before users notice.
Verification and troubleshooting
Fire the schedule manually in a sandbox, pause it, verify a disabled workspace stops producing runs, and confirm a duplicated fire produces one effect. Keep cron expressions in managed configuration, not scattered through task code.