You can give any installed agent a cron schedule so it runs automatically on a recurring cadence, with no webhook and no manual click. Set the schedule from the CLI and the platform fires the agent at each scheduled time.
How it works
Every installation can carry a standard five-field cron expression. */5 * * * * is every five minutes; 0 9 * * 1 is 09:00 every Monday. A background scheduler checks due schedules roughly once a minute and, when a schedule’s time arrives, starts a run of that agent — the same kind of run a webhook or a manual trigger would start. A scheduled run is recorded as a system run, with no human user attached, and trigger type cron.
You manage schedules with three commands:
dry_run and live
A scheduled run has a run mode, set with --env:
dry_run, the default — the agent runs but side-effecting actions are held back. Use this to confirm the schedule and the agent behave as expected.live — the agent runs for real, with side effects.
dry_run is the default on purpose. Live is an explicit opt-in: you must pass --env live to schedule a real run.
last-fired and next-fire
schedule show reports two timestamps.
Last fired is the last time this schedule actually triggered a run. It shows — until the schedule fires for the first time.
Next fire is the next time it will run. The server computes this as the first scheduled time strictly after now, so a frequent schedule never shows a time that has already passed.
Times are UTC
All cron schedules are evaluated in UTC in this version. There is no per-schedule timezone yet. 0 9 * * * means 09:00 UTC, not 09:00 local. schedule show always labels the timezone as UTC to make this explicit.
Good to know
Missed runs during downtime aren’t replayed one by one. If the scheduler is down across several scheduled times, it fires the most recent missed one once when it comes back, then resumes normally. It does not fire a burst for every time it missed.
Changing the schedule resets its clock. When you set or change a schedule, the next run is its next future time. It will not immediately fire for a time in the past.
set --env defaults to dry_run every time. Because set always sends a run mode, re-running set to change only the expression without repeating --env live puts the schedule back to dry_run. Always include --env live when you set a live schedule.
Clearing stops all future runs. schedule clear removes the schedule. The agent stays installed and can still be run manually or by other triggers.
See also
