You already run one flotilla fleet: a set of desks, one XO, one Discord channel,
driven by flotilla watch (quickstart). Federation is the
next tier up — coordinating several fleets at once, each with its own XO, under
one meta-coordinator.
Reach for this when one project has grown past a single XO's span, or when you run multiple projects and want one place to steer them all. If you run a single fleet, you do not need any of this yet — come back when you add a second.
The model is the same hub-and-spoke one tier up, but the roster's immutable
seat_id and parent edges are the org chart. Discord channels are a validated
routing and visibility view. Each project gets its own channel bound to a
project-XO; a #fleet-command channel is bound to a meta-XO whose
members are the project-XOs. A project-XO is to the meta-XO exactly what a desk
is to a project-XO. You DM a project's chief by posting in its channel, or drive
everything from #fleet-command.
Replace the single top-level channel_id / xo_agent with a channels[] list
(the two forms are mutually exclusive — use one):
The example IDs are illustrative; never copy them. workspace init and
register assign a cryptographically random ID when an existing seat lacks one.
IDs are immutable and never reused; parent always references an ID, while
name and surface may change independently. A fully legacy roster with both
fields absent still loads so a deployment can migrate all current seats and
edges in one reviewed commit. Once structured edges are present, an unparented
seat other than the configured fleet root is an explicit Unassigned defect on
the dash.
Routing is by the message's origin channel: a bare message in #fleet-alpha
goes to alpha-xo; @alpha-be there reaches that desk. In #fleet-command, a
bare message goes to meta-xo and @alpha-xo addresses the project-XO. An
@name never resolves outside the channel it was typed in (so a desk is not
reachable from #fleet-command, only its project-XO is).
You can stand up the channels mechanically with flotilla channel create — it
creates the Discord channel via the bot token (idempotent, with a
Manage-Channels preflight) and prints the channels[] binding to paste in. See
flotilla channel --help.
When adding a flotilla group, use the dual-placement layout every existing flotilla in a deployment follows:
COS
└── #alpha-xo C2 / command spine, bound to alpha-xo
Alpha
└── #alpha product hub, bound to alpha-xo
The two channels are intentionally not siblings. The XO's C2 channel lives
under COS, while the product hub lives under the flotilla's category. This
keeps command topology and product topology visible at the same time.
provision-discord realizes the whole shape idempotently: categories, both
channels, both channels[] bindings, and the XO's outbound webhook.
# credential-free acceptance canary: describes every intended object and write
flotilla provision-discord acceptance-canary --dry-run
# live create; emits bindings and the one-time webhook secret assignment
flotilla provision-discord alpha --xo alpha-xo --member alpha-be \
--roster ./flotilla.json --secrets ./secrets.env
# opt in to an atomic, duplicate-safe roster update
flotilla provision-discord alpha --xo alpha-xo --member alpha-be \
--roster ./flotilla.json --secrets ./secrets.env --apply-rosterThe command never writes webhook credentials automatically. Append the emitted
FLOTILLA_WEBHOOK_ALPHA_XO=... line to the protected secrets file; Discord only
reveals a new webhook token once. If a named webhook already exists, the command
skips it and prints the key whose existing value must be retained.
To repair an orphan without raw REST, reparent it by snowflake ID:
flotilla channel move 123456789012345678 --category Alpha \
--roster ./flotilla.json --secrets ./secrets.envchannel edit is an alias for the same idempotent parent edit.
Two channel layouts exist — pick the right one for your goal. The example above is a command-routing layout (an XO's channel lists its desks as
members). Visibility synthesis (the rolled-up fleet view, Tiers 2/3) needs a different member shape — each agent owns its own home channel and lists its parent inmembers[], with the broadcast channel taggedrole="fleet-command". After structured roster migration, that inferred edge is no longer org truth: load checks that it agrees with the rosterparentwherever both express an edge, and refuses disagreement. Synthesis may consume the validated channel view; the dash map consumes roster edges only. See visibility.md → The worked example.
The bot needs the Message Content intent in EVERY bound channel — not just one. With several channels it is easy to grant the intent/permissions in some and miss one. A channel where the bot can't read content delivers messages with empty bodies; flotilla drops empty operator messages (it never injects a blank turn), so the symptom is "my messages in
#fleet-Xdo nothing." Verify each channel with a real@typoand watch for the fallback notice.
The inbound relay must own a given channel exactly once — two daemons opening a gateway on the same channel would deliver every operator message twice. So a federated single-host deployment runs:
- One multi-channel relay daemon — the
watchwhose roster carrieschannels[]; it opens the gateway for the whole set and routes by origin channel. Set the top-levelxo_agentto the meta-XO (as in the example) — that is the XO this daemon clocks (and thestatus/voicetarget). It is orthogonal to the channel bindings; if you omit it the clock falls back to the first agent inagents[]. - One clock-only
watchper project-XO — a roster withxo_agentset and nochannel_id/channels[]. With no channel binding a daemon opens no gateway, so it can never relay a channel the central relay owns; it just clocks its one XO (heartbeat_interval, change-detector, liveness — exactly as a single-fleet clock).
The meta-XO reaches a project-XO the same way a project-XO reaches a desk —
flotilla send --from meta-xo alpha-xo "…" injects + confirms into alpha-XO's
pane. The project-XO's pane is the single inbox: operator-direct (via
#fleet-alpha) and meta-XO-delegated (via send) both land there. v1 federation
is therefore single-host (or SSH-reachable tmux) — the meta-XO must be able to
resolve the project-XO's pane. Cross-host federation over a Discord bus is a
deliberate later phase.
Per-XO outbound. Each XO posts to its channel via its own
FLOTILLA_WEBHOOK_<XO> webhook, created in that XO's channel (see the
quickstart's Discord step). v1 note: the relay's own one-line notices (e.g. "no
agent X; sent to XO") and the audit mirror post under the relay daemon's alert
webhook, not per origin channel.
Per-XO channels split the operator's side-conversations across N channels, so no
single agent sees them all — a desk can act without the cross-fleet picture. The
chief of staff (cos_agent) is the agent that gets the union: flotilla mirrors
every operator↔XO exchange to a durable context ledger it can read and integrate.
Set one roster field (plus an optional path):
{
"cos_agent": "meta-xo", // the agent that integrates who-knows-what
"cos_ledger": "context-ledger.md" // optional; default <roster-dir>/context-ledger.md
}With cos_agent set, flotilla watch appends a line per exchange, both directions:
- 2026-06-18T14:03:05Z · C_ALPHA · operator → alpha-xo · "ship the cache PR when green"
- 2026-06-18T14:05:10Z · C_ALPHA · alpha-xo → operator · "merged; deploying"
- Inbound (operator→XO): a confirmed relay delivery to an XO is recorded,
tagged with the origin channel — so the CoS sees which side-conversation each
exchange belongs to. (An operator message addressed to a desk via
@nameis not operator↔XO traffic, so it is not ledgered in v1.) - Outbound (XO→operator): each
flotilla notifyfrom an XO is recorded too. (A desk'snotifyis likewise not operator↔XO traffic, so it is not ledgered in v1.)
The ledger is a deterministic substrate — flotilla appends structured facts with
no LLM in the write path; the cos_agent reads it on its heartbeat and writes its
integrated view (summaries, the who-knows-what matrix) into its own file, so the
two never collide. The mirror is observe-only: it records traffic the relay and
notify already handle and grants the CoS no command path to any desk — it changes no
relay security rule. Inert when cos_agent is unset (no mirror, no ledger).
Operational notes (v1). The ledger is a durable, append-only record of coordination message bodies (gist-clamped +
%q-escaped, but not redacted — a secret pasted into an operator/XO message lands verbatim), written0o600. Keepcos_ledgeron a local filesystem — the lock-free atomic append relies onO_APPEND-under-PIPE_BUF atomicity, which a networked mount (NFS/overlay) may not honor. There is no rotation yet, so it grows without bound. Retention, redaction, and a machine-parseable format are tracked follow-ups.
cos_agent is a role, not a specific deployment's desk name — point it at whatever
agent plays chief of staff in your fleet.
- quickstart.md — the single-fleet cold start this builds on.
- watch-runbook.md — running the
watchdaemons in production (systemd units, the change-detector). - visibility.md — the stratified-visibility doctrine and the home-channel member shape synthesis needs.
- xo-doctrine.md — how each XO talks to the operator.
{ "guild_id": "G", "operator_user_id": "YOUR_DISCORD_USER_ID", "xo_agent": "meta-xo", "agents": [ { "seat_id": "9dd4bbb777a015a1", "name": "meta-xo" }, { "seat_id": "4555787dfeaac6be", "parent": "9dd4bbb777a015a1", "name": "alpha-xo" }, { "seat_id": "15e9f6d3d03882b2", "parent": "4555787dfeaac6be", "name": "alpha-be" }, { "seat_id": "05bd02999984c6df", "parent": "4555787dfeaac6be", "name": "alpha-data" }, { "seat_id": "41de0c1150340a41", "parent": "9dd4bbb777a015a1", "name": "beta-xo" }, { "seat_id": "311eebb39b84f6a2", "parent": "41de0c1150340a41", "name": "beta-be" } ], "channels": [ { "role": "fleet-command", "channel_id": "C_CMD", "xo_agent": "meta-xo", "members": ["alpha-xo", "beta-xo"] }, { "role": "project", "channel_id": "C_ALPHA", "xo_agent": "alpha-xo", "members": ["alpha-be", "alpha-data"] }, { "role": "project", "channel_id": "C_BETA", "xo_agent": "beta-xo", "members": ["beta-be"] } ] }