Fleet docs v0.2.0-rc.448

A Claude account hits its limit

Each agent uses one profile: one Claude login. When the account reaches its usage limit, the turn ends with a limit error. fleet pauses the profile and every agent that uses it. At the reset time, the agents continue.

Fact Value Code
How fleet finds the limit HTTP 429, or text that matches usage limit, hit your limit or limit reached fleet/internal/driver/claude/claude.go
The reset time From the rate_limit_event, or from the error text claude.go
No reset time known Wait 1 h fleet/internal/supervisor/supervisor.go (UsageWait)
The check for the reset Every 15 s fleet/internal/creds/limiter.go, fleet/internal/server/recover.go
A gate before the limit usage_threshold in serve.yaml: no new turn above this percent. 0 turns it off. fleet/internal/registry/registry.go (UsageGate)
Pacing a burst pace in serve.yaml (#449): a new turn starts only while the five_hour reading plus turn_cost for each turn of the profile in flight stays under five_hour; max_concurrent caps the turns of a profile that sets none. A live chat waiting for input is not in flight: the node names it in its heartbeat's idle list, and an older node that sends none counts every lease. Incident agents go first and are not paced. fleet/internal/sched/pace.go
Spreading over profiles A spawn with no --profile takes the user's profile with the most room (#460, Pace.Spread); a queued turn that fleet placed and that has not started moves to another profile with room when its own holds it (agents.profile_auto, ruling 2026-11-11 23:42). fleet/internal/sched/pace.go, fleet/internal/api/spread.go, fleet/internal/node/spread.go
  • The readings come from the turn's own output stream. The server keeps them when the turn ends, and the Claude usage panel shows them. fleet does not ask a vendor API.
  • Each rate_limit_event names one binding limit, and its unifiedWindows holds every window (five_hour, seven_day, ...). fleet keeps a reading for each window, so seven_day is fresh after each turn, not only after a warning (#302). fleet profile ls --json shows each reading with observed, the end of the turn that read it. A worker token gets 403.
  • Pacing (#449). A reading comes only when a turn ends, so a burst of turns that start together all see the same low reading. pace adds the expected cost of the turns in flight: pace: {five_hour: 80, turn_cost: 5} lets 16 turns start on a profile at 0%, 6 at 50%, none at 80%. A held agent stays queued and its reason names the profile, the reading and the reset time ("profile X is at 62% of its 5-hour window with 4 turns running ...; the window resets at 22:40 UTC"). turn_cost defaults to 5: on 2026-11-11 about 20 turns used a whole window in 15 minutes. Turns are counted on every node, by their agent leases.
  • Incidents first (#449). An agent whose ticket is an open issue labelled type:incident is claimed before the other agents and is not paced: the part of the window above the budget is the reserve it runs on. The label is read from the Work page's kept data, so it needs forgejo_url and a channel with the repo. A limited profile and usage_threshold still hold it.
  • Spreading (#460). One profile at its pace cap while another sits idle wastes the idle one. The room of a profile is the pace budget (100% with no pace) less its five_hour reading and turn_cost for each turn: at spawn its turns in flight and its agents queued (so a burst spawned at once alternates), at a claim its turns in flight. Left out: a limited profile, one at usage_threshold or at its own or the pace's max_concurrent, a removed one, the box login in a fleet with more users, and profiles of another kind or driver than the default (for a move: than the agent's profile). A tie goes to the default. The spawn writes profile_auto: true on agent.spawn; a move writes agent.profile with auto: true, and a move by hand (fleet agent profile) clears it. Only an agent with profile_auto, queued and 0 turns moves: an agent with a conversation stays on the account that holds it. A move is logged (profile move: ... in the scheduler log). Moves happen on node claims; the server's own local scheduler does not move.
  • A paused agent spends no retry.
  • A login that does not work also pauses the profile, with the reason auth. Telegram reminds the owner at most each 6 h (fleet/internal/creds/keeper.go).
  • The API can pause or resume a profile by hand: POST /v1/profiles/{id}/pause and resume.
  • To move one agent to another profile: fleet agent profile <agent> <profile>.
  • Not built, and rejected on purpose: automatic change to another profile at the limit. The spec rejects it (docs/fleet/spec.md). fleet profile rotate changes the secret of a profile. It does not change the profile of an agent.
  • No Telegram message goes out for a usage limit.