Nightshift
Scheduling, catch-up and budgets
An unattended run that fires every role back to back will exhaust a plan's limits long before the work is done. Scheduling exists so the run finishes.
Last updated: July 25, 2026
Quick answer
Each role has a cron cadence, and cadences are deliberately offset so two roles never contend for the same rate limit window. When the machine was off, Nightshift works out which windows it missed and catches up, coalescing them into one run per role by default. A daily token ceiling stops the fleet cleanly rather than failing halfway through the night.
- Five-field cron expressions, plus @hourly, @daily, @weekly, @monthly
- Cadences are staggered so roles do not collide
- Missed windows are caught up, bounded by catch_up_limit
- A restart never re-runs a window that already completed
- The daily token ceiling stops the fleet, it does not break it
On this page
Cadences
cadence: "0 2 * * *" # nightly at 2amcadence: "0 7,19 * * *" # twice daily, 7am and 7pmcadence: "0 */2 * * *" # every two hourscadence: "15 */2 * * *" # every two hours, offset 15 minutescadence: "0 */6 * * *" # four times a daycadence: "30 9-17 * * 1-5" # business hours, weekdays onlycadence: "@daily" # shortcut
Offset your cadences
Two roles firing in the same minute compete for the same rate limit window, which is exactly what pacing exists to avoid. Give each role a different minute. Generated fleets do this automatically and warn if two roles collide.
Match frequency to the work. Building is nightly. Content every few hours. Research and reporting a few times a day. Direction twice a day.
Catch-up after downtime
A laptop asleep overnight is the normal case, not an edge case. On waking, Nightshift asks which firing times it missed rather than silently skipping to the next one.
- once (default): run the role a single time no matter how many windows it missed. Roles carry standing instructions, not queued jobs, so replaying an overnight sleep as six identical content runs would spend six times the tokens for six near-duplicate drafts.
- each: replay every missed window, bounded by catch_up_limit. Appropriate when a role really is per-window work.
- skip: ignore missed windows and wait for the next one.
nightshift serve --catch-up once # or each, or skip
Either way the missed count is reported, so nothing is hidden. A machine that was off for a month never queues hundreds of runs.
Restarts do not duplicate work
Nightshift records when each role last finished a cycle, and considers a window missed only if it fired after that moment. Because a cycle finishes after the window it belongs to, restarting cannot re-fire a window that already ran, however many times you restart.
Budgets and pacing
- tokens_per_day counts every attempt including retries and repairs, and stops the fleet when the ceiling is reached.
- wall_clock_per_cycle bounds a single cycle, so one wedged role cannot consume the night.
- Retries only happen for failures that could plausibly succeed. A rate limit is retried with exponential backoff; an authentication failure or an exhausted turn cap is not, because retrying cannot help.
nightshift status # tokens used today, against the ceiling
Pacing is about finishing, not concealment
Spreading work across the day is how a long run completes inside your plan's limits instead of stopping a third of the way through. Stay inside your plan's limits and inside your provider's terms.
Running always-on
Nightshift runs when your machine is awake. This is the one place a hosted platform has a genuine advantage. If you want around-the-clock operation, run it on a small VPS or any machine you leave on. Otherwise, catch-up on waking covers most of the gap.
nightshift serve --dry-run # what would run, and when it next wakesnightshift serve --once # run what is due now, then exit
Frequently asked questions
What happens if a cycle is still running when the next window arrives?
Nightshift re-plans after every cycle, so a window that passed while a role was working is picked up on the next pass rather than lost. A per-cycle wall-clock limit stops a single wedged role from consuming the whole night.
Why did my role not run at exactly the scheduled minute?
Cycles take time, and roles run in order of the window they belong to. A role scheduled while another was mid-cycle runs as soon as a slot frees. Use concurrency if you want independent roles to overlap.
Does the token ceiling count cached input?
No. Cache reads are not billed like fresh input, so counting them would stop a run far short of its real budget. The ceiling counts input and output tokens across every attempt.
Was this page helpful?
Related articles
Nightshift
The fleet file reference
Complete reference for nightshift.yaml: roles, cadences, modes, sandbox levels, limits and the policy layer.
Nightshift
What Nightshift is
Nightshift runs a fleet of AI agents on your own machine on staggered schedules, driving the Claude Code or Codex CLI you already pay for.
Nightshift
Troubleshooting Nightshift
Diagnose skipped roles, failing gates, exhausted turns, missing connectors and unmerged work in Nightshift.
