Fleet management at platform scale

The Agent fleet management lesson earlier in this track covers fleets you built by hand: loops of 1claw agent create, per-agent vault binding, per-agent guardrails. That works at dozens of agents. It stops working once a Platform API template has bootstrapped a thousand end users, because at that scale the template is the only thing left that describes them all, and nothing aggregates how far the live cohort has drifted from it.

A fleet is simply every agent one template provisioned. The routes answer the two questions a template alone cannot: how many agents are behind the current version, and how do you move them forward without reviewing each one.

1. 1

   Check the fleet's status. version_skew breaks the cohort down by the template version each agent was bootstrapped from; spec_hash tells you whether the current version actually changed anything meaningful, since a version number moves on every edit including ones that changed nothing.

   bash Copy

   1claw platform fleet status $APP_ID $TEMPLATE_ID

2. 2

   Read what is bulk-patchable off the response, rather than assuming it. The allowlist is narrower than a single-agent PATCH and may narrow further over time.

   bash Copy

   1claw platform fleet status $APP_ID $TEMPLATE_ID | jq '.bulk_patchable_fields'

3. 3

   Dry-run a rollout first. A dry run reports the plan and claims no job, so job_id comes back null and it never blocks the real rollout that follows.

   bash Copy

   1claw platform fleet rollout $APP_ID $TEMPLATE_ID --dry-run

4. 4

   Run the rollout. Agents someone edited outside fleet control are skipped, not overwritten, and named in the response under skipped_drifted.

   bash Copy

   1claw platform fleet rollout $APP_ID $TEMPLATE_ID

Every route on this page does what it does a thousand times, and nobody reviews it per agent. That single fact explains every restriction below. A patch that would be unremarkable on one agent, raising a spend limit, turning on transaction signing, is a different kind of act when it lands on an entire cohort in one request. So the fleet surface is deliberately narrower than the per-agent API, not wider.

• Guardrails (max_transaction_value_usd, daily_spend_limit_usd, and the rest) are never bulk-patchable. Raising a limit across a fleet is a thousand separate decisions that happen to share a form, and each one still routes through the per-agent guardrail approval flow.
• Capability flags (intents_api_enabled, execution_intents_enabled) are never bulk-patchable. Turning on transaction signing for a whole cohort in one call is the largest privilege change this API can express.
• A field outside the allowlist returns 400 naming the field, and refuses the entire patch rather than applying the acceptable parts. A partially-applied bulk patch across a thousand agents is worse than a rejected one.
• Hand edits are skipped, not corrected. An agent changed outside fleet control is left alone and the field is recorded on it as drift, the standing answer to "why is this agent still behind". --force overrides the skip but still cannot carry a guardrail or a capability flag, forced or not.
• Only one rollout runs per template at a time. A second returns 409, because two concurrent rollouts would race and leave the cohort split across versions.

Pausing a fleet deactivates every agent in the cohort at once. The blast radius is the point: this exists for the moment you need a thousand agents to stop immediately, not for routine maintenance.