Skip to content
LoopSkill

Documentation · Fleet

Fleet: multi-agent skill sync.

A fleet is a named group of agents that all share the same cookbook. You create the fleet once, subscribe one or more bundles to it, distribute the fleet key to each agent, and from then on all agents stay in sync with a single recipes_fleet_sync call.

Tier requirement: Fleet features require a Pro+ subscription ($100/mo) or higher. Fleet keys (rec_fleet_*) are separate from standard API keys and are scoped to specific bundles.

Concepts

  • Fleet — a named group with a shared fleet key. Created by calling recipes_fleet_create. Fleet key format: rec_fleet_<8hex>_<32hex>.
  • Subscription — links a fleet to a bundle on a channel (stable or latest). Created by calling recipes_fleet_subscribe.
  • Sync — updates all agents in the fleet to the subscribed bundle's current pinned versions. Called per-agent via recipes_fleet_sync.
  • Fleet key — the plaintext key shown ONCE on creation. Store it securely (e.g. in your secret manager). It is NOT re-showable — if lost, create a new fleet.

Step 1 — Create a bundle

Fleets sync from bundles. Create one first if you don't have one: 

// Via MCP (from your agent):
recipes_list_cookbook({})   // list existing cookbooks

// Via API:
curl -X POST -H "x-api-key: $RECIPES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Fleet Bundle"}' \
  https://recipes.wisechef.ai/api/cookbooks

Add skills to the bundle via the dashboard or the POST /api/cookbooks/{id}/skills endpoint. Each skill is pinned at the current latest version when added.

Step 2 — Create a fleet

From inside your agent conversation: 

recipes_fleet_create({ name: "Production Fleet" })

Response:

{
  "fleet_id": "uuid...",
  "fleet_key": "rec_fleet_a1b2c3d4_e5f6...",
  "name": "Production Fleet"
}

Save the fleet_key immediately. It is shown only once. The server stores only a sha256 hash of the key — there is no way to recover it.

Step 3 — Subscribe a bundle to the fleet

recipes_fleet_subscribe({
  fleet_id: "uuid...",
  cookbook_id: "uuid...",
  channel: "stable"   // "stable" (default) or "latest"
})

The channel controls which bundle skills the fleet syncs:

  • stable — syncs only the pinned, reviewed versions in the cookbook.
  • latest — syncs to the most recently published version of each skill, even if the bundle pin hasn't been updated. Use with care in production.

Step 4 — Distribute the fleet key

Each agent that should be part of the fleet needs the fleet key as an environment variable: 

export RECIPES_API_KEY=rec_fleet_a1b2c3d4_e5f6...

Fleet keys are bundle-scoped. An agent using a fleet key can only install skills that are in the fleet's subscribed bundles — it cannot browse or install from the general catalog. This is the security boundary that makes fleet keys safe to distribute broadly.

Distribute via your preferred secret management approach:

  • AWS Secrets Manager / Parameter Store
  • HashiCorp Vault
  • GitHub Actions secrets (for CI agents)
  • A shared .env file on a private host (acceptable for single-machine fleets)

Step 5 — Sync agents

On each agent machine, trigger a sync: 

// Via MCP (from any agent in the fleet):
recipes_fleet_sync({ fleet_id: "uuid...", dry_run: false })

// Via CLI:
recipes sync

The sync response shows what changed:

{
  "fleet_id": "uuid...",
  "cookbooks_synced": [
    {
      "cookbook_id": "uuid...",
      "changes": [
        {"slug": "seo-audit-engine", "from": "1.2.0", "to": "1.3.0", "action": "updated"},
        {"slug": "super-memory", "from": null, "to": "1.4.2", "action": "installed"}
      ],
      "applied": true
    }
  ]
}

Pass dry_run: true to preview changes without applying them.

Listing fleets

recipes_fleet_list({})
// Returns:
{
  "fleets": [
    {
      "fleet_id": "uuid...",
      "name": "Production Fleet",
      "subscriptions": [
        {"cookbook_id": "uuid...", "channel": "stable"}
      ]
    }
  ]
}

Automation pattern: nightly sync

For unattended agents (CI runners, always-on servers), add a sync to your cron or systemd timer: 

# crontab entry (runs at 05:30 UTC, 30 min after carousel refresh)
30 5 * * * RECIPES_API_KEY=rec_fleet_... recipes sync >> /var/log/recipes-sync.log 2>&1

Security considerations

  • Fleet keys are long-lived. Rotate them if an agent is decommissioned or a key leaks. Create a new fleet (or contact support to re-key an existing one).
  • Bundle-scoped. A fleet key cannot install skills outside its subscribed bundles. This bounds the blast radius of a compromised key.
  • No catalog browsing. Agents with fleet keys cannot call /api/skills/search for general browsing — only /api/skills/install for allowed slugs.

Related docs