Fleet docs v0.2.0-rc.448

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.