Routines
A routine is work a bot starts by itself (#601, spec-agents §9). It belongs to one bot. Each run
is a new agent of yours that runs as the bot: its layer, its memory, its model. Runs go through
the same spawn path as fleet spawn, so the dispatcher's pace, ceilings and pause switch govern
them.
Triggers
| Trigger | Starts a run when | Set with |
|---|---|---|
schedule |
the cron line matches, read in the routine's time zone | --schedule "every weekday at 8:30" --tz America/Chicago |
forgejo |
a signed delivery reaches POST /v1/hooks/forgejo |
--repo owner/name (required) and --event push|issues|pull_request|ci (optional) |
webhook |
POST /v1/routines/<id>/hook carries the routine's key |
the key is shown once, when the routine is made |
telegram |
you send /run <routine> to the fleet bot from your linked chat |
nothing more |
inbox |
an item lands in your inbox | --kinds alert,brief (optional) |
A schedule takes plain words or a cron line: every 15 minutes, hourly, every day at 9:00,
daily at 7am, every weekday at 8:30, mon, wed and fri at 6pm, 30 8 * * 1-5. It is saved
as cron. An inbox routine never starts on its own alerts, nor on items its own bot posts.
A webhook is for a CI job or another service. It needs no fleet token:
curl -X POST -H "X-Fleet-Routine-Key: $KEY" --data '{"version":"v2"}' https://fleet.example/v1/routines/<id>/hook
201 means a run started; 401 a wrong key; 409 the routine is paused; 429 it is over a
limit. At most 8 KiB of the body goes into the run's brief.
What a run gets
The brief is the routine's prompt, then what started it (the schedule time, the push, the webhook body, the inbox item), the expected result, and the no-data rule: by default, "if the data is missing, report that and stop; never fall back to stale or made-up data". A run posts to your inbox only when something needs you.
A run with a --project gets its own worktree on branch fleet/<run name>; one with a
--workdir runs there; one with neither starts in a neutral home on its node.
Limits
--min-interval 10m: the least time between two runs of the routine.--per-hour N: runs per hour of the routine.- Runs per hour of one bot over all its routines: 20 unless the server sets another.
--budget USD: the routine's spend in any 24 hours. Each run's budget is what is left.
A run over a limit does not start. It is recorded as refused with the reason, and an alert goes to your inbox (one per streak of the same refusal). Test keeps the per-hour limits and the budget but not the minimum interval.
Pause, and the unattended pause
fleet routine pause <routine> stops every trigger but Test. When you have not had the page
or the inbox open for 7 days, your routines pause by themselves (paused: unattended) and the
inbox asks whether to resume them. Approve resumes them all. The fleet's owner sets the 7 days
in serve.yaml (routines: {unattended: 168h}; off turns the pause off).
Commands and the page
fleet routine new ops morning --schedule "every weekday at 8:30" --tz America/Chicago \
--prompt "Brief me on red CI and stuck agents." --expect "a short brief in my inbox" --per-hour 2 --budget 2
fleet routine ls
fleet routine test morning # a run now, real work
fleet routine runs morning # the history: trigger, state, agent, cost, reason
fleet routine pause morning; fleet routine resume morning
fleet routine set morning --schedule "every day at 7am"
fleet routine rm morning
The Bots page (/bots) lists your routines with their next time and last run, and has
Test, Pause/Resume, History (each run with a link to its turn) and New routine.
Your routines are yours: no other person sees them. A routine of a fleet bot runs as the person
who made it.