fleet

A subscription-safe bridge that lets a lead Claude Code session on Pro/Max delegate work to members running on other models and other vendors — without ever putting a proxy on the lead.

New here, or here to operate it? Start at 13 User Guide. That page is written against the running system: install, configure, run, delegate, and the traps. This page explains the shape of the design and why it was chosen.

Sibling of crush-bridge (Tier 2 → headless Crush on GX10 DeepSeek). fleet keeps a Claude member a real Claude Code process so it inherits CLAUDE.md, hooks, skills, and MCP — just pointed at a cheaper model. It also runs non-Claude members (kind: opencode) as first-class peers.

Leading approach — herdr-centric message server (`fleetd`)

A small always-on message server, fleetd, controls herdr (an agent multiplexer, "tmux for agents") over its Unix-socket API and exposes a clean 2-way messaging API as an MCP server that both the primary and the workers mount — one unified Claude setup and the sole communication gateway. A plain REST surface covers the same features for non-Claude clients; there is no event-stream route. Any broker is fleetd-internal, below the gateway. herdr owns the PTYs, multiplexing, persistence, and agent-status events; fleetd owns policy (subscription boundary, session lifecycle, status-gated delivery) and the client contract. A Claude member launches with ANTHROPIC_BASE_URL pointed at whichever gateway its profile names, plus a bearer token. The allowed hosts are a config value, so they differ per deployment. The lead stays env-clean and calls fleetd's MCP tools.

flowchart LR
    OPUS["Opus — primary<br/>(Claude Code, env CLEAN)<br/>MCP client"]
    subgraph BD["fleetd — standalone daemon (not a claude process)"]
        SRV["SERVER face<br/>MCP · REST · policy"]
        CLI["CLIENT face<br/>status-gated injector · herdr socket"]
        SRV --> CLI
    end
    HERDR["herdr<br/>panes · agent-status"]
    W["member pane<br/>ANTHROPIC_BASE_URL set<br/>MCP client"]
    M["the configured gateway"]

    OPUS -->|"MCP fleet_send (blocks)"| SRV
    W -.->|"MCP fleet_reply"| SRV
    CLI -->|"Unix socket<br/>agent.prompt · status polling"| HERDR
    HERDR -->|"drives PTY"| W
    W -->|"inference"| M

    classDef ext fill:#2b6cb0,stroke:#1a365d,color:#ffffff;
    classDef core fill:#2f855a,stroke:#22543d,color:#ffffff;
    class OPUS ext
    class SRV,CLI,HERDR core

Subscription boundary: the lead never sets ANTHROPIC_BASE_URL (stays on Pro/Max). Only a member process is moved off-subscription, and only by the daemon, at spawn; fleetd is a plain daemon with no Anthropic quota, so it may poll and subscribe freely. One exception, and it costs money: a profile marked subscription: true runs its members on your plan on purpose — see 13 User Guide → The knobs that cost money. An opencode member sits outside this boundary entirely and uses its own provider credential.
One gateway: fleetd is the sole communication path for every session. The lead and every member mount it as an MCP server and talk only to it — no session ever addresses a broker, a peer, or the network directly. How the mount happens differs by backend: a claude-code member gets one claude mcp add line or a shared .mcp.json, while an opencode member gets a generated opencode.json and no ANTHROPIC_* variables at all. Any broker or queue is fleetd-internal, below the gateway — and it is optional. With broker: commented out the daemon uses an in-memory inbox; when it is on, it is LavinMQ over AMQP.
How the lead gets a reply: in the simple case, one blocking MCP tool call (fleet_send) that fleetd holds open until the member replies (fleet_reply) or its turn completes, then returns the reply as the tool result. In practice that call is capped by the lead's own MCP client timeout (about 60 seconds), so real work uses wait:false and a ticket instead. Either way the lead never busy-polls and never touches a broker: when a detached ticket goes terminal, fleetd injects the lead's own idle pane to wake it.
Different model per member process sidesteps Claude Code's lack of per-subagent provider routing — the worker isn't a subagent, it's its own configured process.
AgentAPI (coder/agentapi) was considered and dropped: it was never built. No AgentAPI code exists under fleetd/src/main/java, and the shipped injection path is the herdr one, which every profile selects through Profile.kind (claude-code or opencode, FleetConfig.java:265-270). See Approaches for why herdr won and Message Server for the full design.

Pages

Read in order (the sidebar mirrors this):

Architecture — process model, the two invariants, two traffic modes
Message Server — 🟢 fleetd, the herdr-centric message server (primary approach)
Approaches — herdr-centric vs AgentAPI vs Agent SDK vs bus/tmux (research matrix)
Setup — 🟠 stub, never written. Use 13 User Guide §2 instead.
Operations — 🟠 stub, never written. Use 13 User Guide §4 and §6 instead.
Team — a lead orchestrating a mixed-vendor fleet
Use Cases — the code-review scenario, the mechanisms, and the portable CLAUDE.md block
Roadmap — stages, tech stack, and tickets
Implementation — as-built code map, classes, flows, state machines
Cross-Host Messaging — broker topology, exchanges, queues per entity
Features — what it can do, the knob that turns it on, why it exists, the gotcha
Claude → OpenCode — porting a workspace to a second host
User Guide — 🟢 the operator page. Install, configure, run, delegate, and the traps.
Fleet Manager — the separate tool that shows several fleets on one host
REST API Reference — every route, the role it needs, and its real body
Security & Trust Boundary — the subscription guard, the role table, and what a member's pane inherits

Status

🟢 Running. The daemon is live on this host. Chapters 4 and 5 were never written past their scope note, and chapter 13 replaced them.

This page does not carry release numbers, ticket counts or test totals. Those go stale within days and then read as current facts. See 8 Roadmap for the delivery record.

The herdr-centric fleetd message server was selected on 2026-07-11, superseding the AgentAPI plan of 2026-07-08. AgentAPI was considered and dropped: it was never built, so there is no fallback injector to switch to. See Message Server for the design and 13 User Guide for how to run it.

📖 fleet

Home — overview & the decision

Chapters

Architecture — system · 2 invariants · 2 modes
Message Server — the fleetd design
Approaches — transports compared, why herdr
Setup — ⚫ superseded by 13
Operations — ⚫ superseded by 13
Team — orchestrating a mixed fleet
Use Cases — the review scenario + mechanisms
Roadmap — delivery record: what is live, what is off, what was dropped
Implementation — as-built code map · classes · flows · state machines
Cross-Host Messaging — broker topology · exchanges · queues per entity
Features — what it can do · the knob that turns it on · why · the gotcha
Claude → OpenCode — porting a workspace to a second host
User Guide — 🟢 install · configure · run · delegate · the traps
Fleet Manager — many fleets on one host, over REST
REST API Reference — all 14 routes, roles, and bodies
Security & Trust Boundary — the guard · authz · what a member inherits

Design proposals (not built)

CB-548 Lead Quorum — a deterministic decision procedure around a lead's judgment

🟢 herdr-centric fleetd · AgentAPI = research, never built

fleet

Leading approach — herdr-centric message server (fleetd)

Pages

Status

📖 fleet

Leading approach — herdr-centric message server (`fleetd`)