Agent fleet management

When you run dozens or hundreds of agents you need repeatable patterns for enrollment, vault layout, and lifecycle. Bulk provisioning plus tight policies keeps the blast radius small.

• Shared vault with path-scoped policies: api-keys/** shared, agents/{name}/** per-agent
• Per-agent vaults for strict isolation in multi-tenant or compliance setups
• Vault binding via vault_ids limits which vaults an agent JWT can touch even if a policy is too broad
• Conditional policies add ip_allowlist and time_window on sensitive paths

1. 1

   All steps below use the CLI session from 1claw login. The TOKEN export is not needed.

   bash Copy

   # Verify you are logged in:
   1claw whoami

2. 2

   Bulk provision agents with the CLI. The --scopes flag sets OAuth-style scopes. Fine-grained access is controlled by vault policies (see Agents & Access Control track).

   bash Copy

   for name in worker-1 worker-2 worker-3; do
     1claw agent create "$name" --scopes "vaults:read"
   done

3. 3

   List agents and pick one to configure further.

   bash Copy

   1claw agent list
   export AGENT_ID="paste-worker-1-uuid-here"

4. 4

   List or create vaults and export their IDs.

   bash Copy

   1claw vault list
   export VAULT_1="first-vault-uuid"
   export VAULT_2="second-vault-uuid"

5. 5

   Bind each agent to just its intended vaults so a stray policy cannot widen access.

   bash Copy

   1claw agent update $AGENT_ID --vault-ids "$VAULT_1,$VAULT_2"

6. 6

   Set transaction guardrails for any agent using the Intents API.

   bash Copy

   1claw agent update $AGENT_ID \
     --tx-max-value-eth 0.05 --tx-daily-limit-eth 0.5 --tx-allowed-chains "base"

7. 7

   Rotate an agent's API key, which invalidates the old credential. There is no CLI subcommand for this one: 1claw agent keys rotate rotates a per-chain signing key, which is a different thing. Use the API or the SDK.

   bash Copy

   # The CLI rotates signing keys, not the agent API key.
   # Rotate the API key through the API or SDK:
   curl -s -X POST https://api.1claw.co/v1/agents/$AGENT_ID/rotate-key \
     -H "Authorization: Bearer $ONECLAW_TOKEN"
   
   # SDK equivalent:
   #   await client.agents.rotateKey(agentId);

8. 8

   Deactivate the agent when its task is done. This keeps the audit trail, unlike delete.

   bash Copy

   1claw agent update $AGENT_ID --active false

You now rotate a key and deactivate an agent while keeping its audit trail, and you can scope a fleet with vault binding and conditional policies.

Where this goes wrong in practice. Fleets fail by accumulation. No single agent is a problem and the set becomes one.

• Agents are created and never retired. Deactivation preserves the audit trail where deletion does not, and the absence of a retirement step leaves a growing population of live identities nobody owns.
• Policies drift between agents that should match. Three agents doing the same job diverge one exception at a time, and the widest one becomes the effective posture.
• Blocked events are unmonitored. Denials are the cheapest signal available precisely because nothing breaks when they fire, and they indicate either a broken client or a steered agent.
• Environment tags are set but not enforced. Tagging without env.enforce_agent_environment_scope is documentation, not a control.