Fleet docs v0.2.0-rc.448

3. Claude logins: profiles

Each turn runs Claude Code, so each turn needs a Claude login. A profile is one login that fleet keeps for you. The login is a subscription token or an API key.

  • Add a profile: fleet profile add main --kind subscription --default. The value comes on stdin, never as an argument.
  • Each agent uses one profile: yours, or the one you give with fleet spawn --profile. An agent never uses the profile of another person.
  • The turn gets an access token only. The refresh token stays on the server.
  • When the account reaches its limit, the profile is limited until the reset time. Its agents are paused and spend no retry. They continue at the reset. See a usage limit.
  • fleet profile ls --json gives each profile's latest five_hour and seven_day readings: percent, reset time and observed (when the turn that read it ended).
  • usage_threshold in serve.yaml stops new turns before the limit, at a percent that you set.
  • pace in serve.yaml paces a burst on one profile: pace: {five_hour: 80, turn_cost: 5, max_concurrent: 8} starts a turn only while the latest five_hour reading plus 5% for each turn in flight stays under 80%, and at most 8 at once. A live chat waiting for your next message is not a turn in flight: only a reply in progress counts. The rest wait queued, and the reason names the profile and the reset time. Agents on a type:incident ticket go first and are not paced.
  • A spawn with no --profile goes to your profile with the most room (#460): the five_hour budget of pace (100% with none) less the latest reading and turn_cost for each of its turns running or queued. A profile that is limited, at usage_threshold or at its max_concurrent is left out. A tie goes to your default, and only profiles of the default's kind and driver count (a subscription turn never goes to an API key). With no room on any, it waits on the default. The reason of a queued agent and the placement line (fleet ls, the Work card) say spread to profile P: the most room, ..., with what holds each other profile.
  • A turn that fleet placed this way and that has not started moves to another of your profiles when its own holds it and the other has room: spread to profile P: moved from Q, which held it, also in the scheduler log. A profile that you named with --profile never moves, and fleet agent profile <agent> <profile> moves one agent by hand.

You do not need a terminal on a machine to add a login: Sign in on the Accounts tab of /admin (or fleet profile signin claude <name> --reason TEXT) has fleet run the vendor's login on a node and gives you a link to approve. See Admin.

The Claude usage panel shows each profile and its last readings.

Next: 4. Agents that start agents. An agent can spawn workers of its own.