Routines and responsibilities
Two ways to give a coworker work that outlives one conversation. A routine runs on a schedule. A responsibility pursues a lasting goal and runs when an event arrives.
3 min read
A routine: on the clockCopy link to this section
An instruction and a schedule. The schedule is a cron expression read in the routine's own timezone, or one moment written as @once 2026-12-24T09:00. At each due time the coworker carries out the instruction, and every run is kept in the routine's history. You can also run it now, and so can an API key with the write:routines scope.
A responsibility: a lasting goalCopy link to this section
One coworker, a goal, an instruction and the criteria for success, plus the events it cares about. It does not run on a clock. It runs when one of those events arrives, for example from Slack, GitHub, Linear, Sentry, PagerDuty, email or a webhook, and it stays active until it is paused or completed. An outside sender is checked with that service's own signature before anything is queued.
ExamplesCopy link to this section
| The job | Use | Set up as |
|---|---|---|
| Every weekday at 09:00, summarise yesterday's support tickets | Routine | 0 9 * * 1-5 |
| Once, on 24 December at 09:00, post the holiday rota | Routine | @once 2026-12-24T09:00 |
| Triage each new GitHub issue until the backlog is under control | Responsibility | github |
| Keep the on-call channel informed about every PagerDuty incident during a migration | Responsibility | pagerduty |
Ask on the clock: a routine. Ask "whenever this happens, until we are done": a responsibility.
The 15-minute minimumCopy link to this section
A routine runs at most once every 15 minutes. The server enforces this whatever the schedule says or a model suggests: a schedule whose runs come closer together is refused.
A run held up by a restart or a busy queue is still delivered when it is at most 10 minutes late. Older due times are not replayed: the schedule picks up again from now, so a quiet month does not come back as thirty runs at once. A one-off time that passes while scheduled routines are not running does not fire, and its history says so.
When scheduled routines runCopy link to this section
Scheduled routines start once the workspace is up, and are started again by themselves if they stop. Signed in, the status page shows whether they are running.
They fire only while the workspace is running. If it is asleep, paused or restarting, nothing fires, and on waking the rules above apply. During a restore from the operations page scheduled routines are paused and start again afterwards. Each firing is dispatched once, even across a restart.
Responsibilities do not depend on the schedule: their queued runs are picked up as soon as they arrive.
Last updated