Fleet UI: linked nodes¶
This page covers the parts of the dashboard you see once this node is linked to others through federation: switching nodes, seeing several at once, the fleet map, and ⚙ Fleet config. To link your first two machines, follow the setup walkthrough.
A peer only ever shows what it shares with you: the grants it gave you decide what its cards, views and pages can read or change.
Node chips and switching¶
The right end of the tab bar picks the nodes the dashboard shows. With up to four nodes there is a button for this node (⌂) and one per trusted peer, with a dot for its presence; past four they fold into one dropdown that names the node on screen, filters as you type and keeps this node first. Click a node to open its own dashboard; ⌂ returns to this node. Alt 1 is this node and Alt 2…9 the peers in order; the shortcut never fires while you type in a field or a web terminal has focus. The row is always there and adds no height to the page, but it is greyed out (its tooltip says why: federation is off, or the hub is unreachable, still connecting or refused the connection) until this node is connected to its federation hub, and greys out again if that connection drops; it follows the connection without a reload (within about five seconds while federation is on; with federation off it rechecks every couple of minutes). Once connected, ⌂ works with no peers at all; each trusted peer adds a button. Fleet ends the row: the third place you can be, after this node and another node. It is lit on the fleet views and opens the one you used last (the map, or ⚙ Fleet config). It is never greyed out on this node: while the hub is not connected it opens ⚙ Fleet config, where the hub connection and the first peer are set up. Its dot is lit while connected. On a node that was never set up it has a set up pill until you have opened the setup guide once. In a peer's view it opens the map, and hides while there is none. nodes ▾ stays greyed out until the hub connects; with no linked node yet it opens with a "No linked nodes yet" note. ⌂ always works where it leads somewhere: home from a peer's view, and back from the fleet views.
Fused nodes¶
nodes ▾, after the node buttons, shows several nodes together: tick the
nodes (all by default), and Groups lists the ticked nodes' groups as one
tree (see Groups on several nodes),
Terminals shows the open terminals on the ticked nodes, a peer's labelled
with its node — its initial on the tab, the full name in the pane header — while
this node's go unlabelled (the others stay open, out of sight), and Messages
their mail (see Messages on several nodes); the
button reads e.g. 2/3. Clicking a node's name (or its only) shows that node
alone, as does unticking all but one. A fused view is always this node's page:
the peers in it show what they share with you, so this node's own groups and
controls work as on its own view. Fusing from a peer's page goes to this
node's page, and so does an address that names both a peer and a fused set.
Every other tab shows this node, says so in a strip at the top, and a peer's
own view opens from its node button. The header's quota bars show one node at
a time, because quota percentages do not add up across machines. A node pill
before them names whose they are (this node by default), and its menu lists
each ticked node's peak quota. A node that does not share usage
(costs.read) is locked there, with the reason. Usage opens with a per-node summary: each
ticked node's spend today and this month, and its peak quota. The spend is
totalled across the nodes that share it; quota is shown per node only. The
views below it show this node.
Automations lists this node's jobs, then each ticked peer's under its
node pill, with the same filter, kind and page. A peer that trusts you
unrestricted shares its list, and its cron jobs and standing orders run,
pause and delete in place through its routes. Editing one opens on that
node's own view. A peer's exports stay on that node, and a peer that shares
less is locked, with the reason.
Diagnostics › Audit gets a node filter: this node, one ticked peer
(paged through its routes, under federation.audit.read), or all nodes,
which merges each node's newest page newest first, with a node pill on each
row and the nodes that withhold theirs shown locked. Logs and
Performance are one daemon's own, so they get a node switch instead:
this node or one ticked peer, read through its routes when it trusts this
node unrestricted (anything less shows why it is refused). On Access, one
machine's own settings, the strip also names each ticked peer, and an
unrestricted peer's Access opens on its own view from there. On Config
the strip is a node picker over the ticked nodes: the tab edits one at a
time, this node first, and a picked peer in the same way as on its own page
(see On a peer's page).
Plugins and Processes keep each node's set intact: this node's as
before, then a section per ticked peer under its node pill. A peer that
trusts you unrestricted shows its plugins (check, run, install from its
catalog, delete, all on that node) and its process templates (delete there;
open and edit on its own view). A peer that shares less is collapsed and
locked, with the reason. The fused set is part of the address
(?nodes=all, or the ticked instance IDs), so a reload keeps it.
The map¶
Fleet at the end of the node row opens the fleet views. Once a hub is
connected, the tab strip turns into their switch: Map and ⚙ Fleet config.
Until then Fleet opens ⚙ Fleet config and the tabs stay as they are. The right
end stays the same, with Fleet lit.
[ / ] step back to the tab you came from.
Each ⚙ Fleet config section has its own address (/fleet-admin/peers,
/fleet-admin/grants, …) and its own history entry, so Back/Forward step
between sections and a section can be bookmarked. Peer grants narrowed to
one peer or pool is /fleet-admin/grants/<id>. Bare /fleet-admin opens
the setup guide until setup is done, else Peers. The map's shortcuts into
Fleet config (⚙, grants…, trust…, Hub page…) are links, so a middle-click
opens the section in a new browser tab.
The map draws this node and each peer as a card joined by link edges (solid: reachable; dashed: unreachable or stale). A card shows the shared agents and how many are online, agents waiting for input, cpu/mem/disk, the tclaude version (↑ when a newer release is known) with its health, and how many features the peer does not share with you (hover for the list). Open dashboard opens that node's Groups page. Cards are polled only while the map is on screen; an unreachable peer keeps its last data, marked with its age.
The toolbar above the map holds Show hub (remembered per browser; off, the hub card goes and links run node to node, with the hub's state in the toolbar) and zoom: scroll or pinch to zoom around the pointer, drag the background to pan, or use −, the percentage (back to 100%), + and fit. A map larger than the window fits itself until you zoom or pan. Phone-width screens keep the stacked layout without zoom. At its right end, 💰 fleet limits (💰 fleet N% once limits exist) reads this node's fleet usage limits and opens them (see Fleet limits).
Cards link to where their settings live: ⚙ opens the peer in Fleet config ›
Peers, and beside You trust it trust… opens Peers and, while the peer is
restricted, grants… opens Peer grants on that peer. The hub card says whether
this node is a hub admin and opens Fleet config → Hub. A peer view of the map
shows no such links: Fleet config lives on this node's own page.
Trust between two nodes can differ by direction, so the map always names both.
A peer card shows You trust it (what the peer may do on this node; you set
it) and It trusts you (what this node may do on the peer; its operator sets
it). Each link's label shows both directions on one line, such as → limited
← ⚠ full access: → is what this node may do on the peer, ← what the peer may
do here (hover a direction for the node names). Click it for a plain-language
explanation and a shortcut to Fleet config. A peer on an older tclaude does not
report its side ("not reported").
Show untrusted (in the legend) adds the instances visible on the hub that this node has not trusted, as dotted cards with their self-reported name, instance ID and fingerprint. Trust… opens the same dialog as ⚙ Fleet config → Peers: compare the full fingerprint with that node's operator, pick a label and a trust level, and confirm. The box is remembered per browser. Trusting an instance from the map also asks it to trust this node back.
An instance that asked to be trusted shows on the map even with the box off, as an amber card first in the untrusted section with its note (its own words) and whether it already trusts this node; the top bar counts the requests. Dismiss forgets a request. Ask to be trusted… on any other untrusted card sends this node's own request, with an optional note.
To update a node: click update… (or installation…) on its card, check the
version and warnings, then Update to vX… and confirm. The node replaces its
binaries (keeping the old ones for Roll back…) and restarts its daemon;
agent sessions keep running and the dialog follows the job through the
restart. Updating a peer needs its node.update grant. The same dialog
shows how the node starts and its update settings; see
Updating local and linked nodes. CLI:
tclaude update [--node PEER] --check|--apply|--rollback.
A peer's dashboard (remote node view)¶
Opening a peer shows the normal per-node dashboard, served through this
daemon's peer proxy (the URL carries ?node=inst_…). The peer's name replaces
the title, a thin line in its colour runs along the top, its chip is current,
and a peer-view pill lists what it shares.
Messages shows the peer's mail when it grants you node.messages.read, in
the same client as this node's: folders, filters, bulk bar, pager, reader and
attached files (agent mail's and startup briefings' too). Read state on agent
mail needs its node.messages.manage. Its
human notifications carry the same buttons as this node's (reply, focus, mark
read/unread, download, delete). Opening one marks it read on the peer, and
mark read/unread and the folder's mark all read go to the peer, when it grants
you node.messages.mark-read; reply needs its unrestricted trust. Download builds
the Markdown or zip from the peer under node.messages.read. Focus opens the
sending agent's terminal here through the federation bridge (as its Groups
row's attach does, so the peer's sessions.watch / sessions.attach decide),
never a window on the peer's host, and marks the notification read. Deleting
(a message, the selection, delete read) and wiping work when the peer trusts
you unrestricted. A control the peer withholds stays in place, disabled, with
a 🔒 whose hover names what it needs. Its access requests are answered in the
fused Messages view.
A group's quick options — description, default directory (typed: the folder
browser reads this machine), member cap, default profile, sandbox profile and
attachment — its rename, and the ⚙ menu's settings dialog, startup context,
notifications, remote policy and nesting work as on this node when the peer
grants groups.settings for that group (unrestricted trust holds it), and its
shut down and power on buttons under groups.members.stop and
groups.members.resume there. The
settings dialog sends only what you changed and disables the fields the peer
keeps. The default directory, default saved prompts and sandbox profile also
need the matching spawn grant, and the
profile pickers the peer's node.spawn.read (Changing a peer's groups).
Greyed-out tabs, buttons and menu items are ones the peer does not offer you.
They stay in place so the layout does not jump; hover or click one to see why,
including the grant the peer would have to give you (or "unrestricted trust"
for what no grant opens). The Groups tab shows every group the peer shares
anything in: a roster, presence or mail grant alone shows its members, and
agents.status.read adds their activity, model, task and context.
The peer-view pill names both directions of trust and lists what is hidden
from you, with the grant each needs. Usage
and costs say when they are not shared.
If the peer granted you lifecycle actions, its agents' status dot (stop or
wake), restart, sandbox restart, retire and clone controls open the same
dialogs as on the peer itself, sent to the peer. Options the peer keeps for
its own operator stay in place, locked with a 🔒 naming what they need (its
unrestricted trust): deleting the worktree on retire, and a clone's group
ownership and worktree. Recreating a missing launch directory on wake is left
out. A peer that trusts you unrestricted offers them all, as on the peer.
Turning an agent's sandbox off takes unrestricted trust. With a move grant,
the ⚙ move here… item opens the regular move dialog, to a group on this
node. CLI: tclaude federation action <action> --node PEER --agent ID.
Messaging a peer's group (its ✉, or the palette) opens the regular message
dialog, titled with the node. Under the peer's message.direct grant it
sends one message per ticked member, from you, the operator. From and the
role filter stay in place, locked with a 🔒 that names what they would need
(its unrestricted trust); hover or focus the 🔒 to read it.
A group's spawn button (and any other way of opening the spawn dialog on a
peer view) opens the regular spawn dialog, aimed at the peer. Every control
stays in place; the ones the peer decides are disabled with the reason on
hover. You always set the name, display role and initial message (the brief);
a profile from the peer's selectable list; and every other launch setting
(directory, harness, model, effort, roles, sandbox profile, permission and
sandbox modes, environment, ownership, harness features, saved prompts,
worktree) only where the peer allows it (an unrestricted peer, which gets the
dialog as a local spawn, or its groups.members.spawn.* grants). With
node.spawn.read the dialog pre-fills and shows what the peer applies, and
offers the peer's and this node's profiles and saved prompts (see
The remote spawn dialog). Without a spawn grant the
request waits for the peer's operator, who decides those settings when
approving. The
directory is typed as a path on the peer — the folder browser reads this
machine. After submit, a toast follows the request until the peer decides.
Every dialog follows one rule for what another node keeps. Its operator's
own controls (a member's group ownership and permissions, a clone's ownership
and worktree, retire's worktree deletion) work where that node trusts you
unrestricted and are locked with a 🔒 reason elsewhere. On another node, the
spawn dialog's Save as profile… opens the profile editor with a Save on
choice: that node (under unrestricted trust or node.spawn.profiles.create,
which saves it operator-only) or this one. A group picker's + new
profile… stays locked there. In the palette, commands that only
unrestricted trust reaches (Snapshots…, Announce to all live agents…) show
disabled with that reason on any other peer. Controls that only
work on this machine (the folder picker, the saved prompts picker in group
settings) are locked with their reason for any other node and on a peer's
page; type the path instead.
The Groups toolbar's global default spawn profile, global sandbox profile and
+ new group controls work on a peer view the peer shares them in
(node.spawn.defaults.manage, node.groups.create; unrestricted trust holds
both), and are greyed with the reason otherwise. See Managing a peer's node.
In a fused view those three controls act on one of the listed nodes, which a
chip in front of them names in the node's colour. It starts on the page's own
node and follows the node of the group you last act on: a click on its header
or one of its controls, a right-click, or a drop onto it (hovering, or a click
on its plain text or empty space, does not move it). The chip flashes when it
moves, and picking another node in it moves it by hand. Turn off Config ›
Appearance › Header & rows › Toolbar follows the clicked group
(dashboard.fused_toolbar_fixed_node: true) to stop the following: the
toolbar then moves only when you pick a node in the chip. Another node's controls show and set that
node's defaults and create the group there, as far as it shares them with you
(the same grants as on its page); new profiles are made on their own node. The toolbar also
carries 💰 fleet limits, this node's fleet usage limits, whichever node it follows.
A peer's agent terminal opens in the browser as a remote terminal (watch-only
or interactive, as the peer's sessions.* grants allow; see above).
tclaude federation attach <agent-id>@<instance-id> attaches from your own
terminal.
Requesting access from a peer¶
Each feature in the pill's "Hidden from you" list has a request… link. It asks
the peer's operator for the grant that feature needs: how long it lasts (1
hour to 30 days, or permanent) and a reason. A group permission asked for
without a group covers every group on the peer, including future ones; the
peer's operator may narrow it to one group (the CLI's --group-id asks for one
directly). Local-only features such as terminals have no link. The
dialog follows the request until the peer's operator approves or declines it,
or it times out after 5 minutes; an approved grant shows up on the view's next
refresh. A peer only takes requests from nodes it already shares something
with. CLI: tclaude federation access request --node <peer> --permission <slug>
[--group-id …] [--ttl …] [--reason …], then access status.
Groups on several nodes¶
In a fused view, Groups lists every group on the ticked nodes, named
group@node with the node's colour on the suffix. It is the same Groups view
under the same toolbar: the filter and
▾ view (offline members, columns, and the virtual groups) apply to every
node's groups, and the filter counts them all. The virtual groups (Ungrouped,
Retired, Conversations, Replaced generations) show per node, named
Ungrouped@node and so on: this node's work and page as on its own view,
and a peer that trusts you unrestricted shows its own (their first page, read
through its peer routes). A restricted peer's are not shared. Process runs show on this node's own groups; a peer's runs are
not shared across nodes, so its groups say so instead. On a peer's rows, the
controls that peer shares with you run through its peer routes, exactly as on
its per-node view: the status dot (stop, or wake a stopped agent), restart,
sandbox restart, retire, clone, the group's spawn button (the regular spawn
dialog, aimed at that node, as above), its ✉ message button (one agent at a
time) and the group settings it grants (groups.settings, as above: the
quick options, rename and the ⚙ menu's settings items), which go to that
node's own group. Under unrestricted trust a peer's rows also take what no peer
grant covers: advancing a process, re-briefing or standing down a force, group
ownership, the auto-join default, promoting, reinstating, hiding a window,
deleting a past generation, member permissions, sudo, new cron jobs, standing
orders, saving as a template (edited afterwards on that node's own dashboard),
pulling, syncing and cleaning up its repositories and worktrees, and links
(within that node: a link from its group offers no cross-node targets). Each
opens the dialog it opens here, reading and saving on that node. This node's groups work as on its own view; on a peer's
page their group settings still go straight to this node. Everything else stays an overview: click a group's @node
suffix to act on it in that node's dashboard. An unreachable node keeps its last rows, marked
stale; a node no longer trusted drops them. The old /fleet address opens this
view with every node ticked. CLI: tclaude agent groups ls --all-nodes; actions are
tclaude federation action ... --node NODE.
An agent that teleported off its home node is marked on both ends, in single-node
and fused views alike:
- Where it runs now: its row carries an away from <home> · hop N badge in
the home node's colour.
- At home: it leaves a dimmed away → on <node> placeholder in each of its
groups, with no controls. The placeholder is not counted in the group's
member count; the header shows +N away instead. In a fused view, ↓ show
scrolls to its live row; in a single-node view, open on <node> ↗ opens that
node.
- Back home: once it returns, its row shows a back home tag for ten
minutes.
The markers come from the agent's federation presence (tclaude agent whoami
shows the same).
To send an agent elsewhere without dragging, use the send elsewhere section of
its row's ⚙ menu (single-node and fused views). Each item opens one dialog with
a mode bar: Move to a group on another node, Clone (here, continuing in
the clone dialog), Morph into another spawn profile (a dry run previews the
change and what happens to the history; for another harness, its History
carry-over section sets the target window, the budget, what is cut first, how
a large cut is handled and, under Advanced, how much of each category is kept,
with a live estimate from the dry run; Keep a backup leaves a stopped clone of
the agent's current form), Teleport to another node (its home
keeps a placeholder), and Recall home (from the placeholder at home, or ⌂
⌂ recall home… where it runs: straight to its origin, retaking its home identity). Another
node's agent offers move here and clone (on that node), plus Morph when that
node trusts this one unrestricted. Dropping an agent
onto another node's group opens the same dialog on Move, pre-filled. A peer's
agent moves here, or, when that peer trusts this node unrestricted, on to a
third node: the peer sends it, and its own ⚙ Fleet config → Moves follows it. In the
fused view a drop onto a group on the agent's own node works as on that node's
Groups view (move or add to a group, retire to the bin, and Ctrl-drop (⌘-drop on a Mac) to
open the clone dialog for that group) — for this node always, and for a peer that
trusts this one unrestricted. A peer's group controls there (create a subgroup, delete a
stuck pending spawn, and the rest its grants cover) act on that peer; the few that
only its own dashboard runs (the links manager, its messages, sudo) are
greyed out; hover or focus one to see why, with the grant it needs, as on the
peer's own page. Each node's links show on its own groups there, and its triggers and queued spawns
too for this node and peers that trust it unrestricted (a queued spawn launches,
edits and discards on its node). Group headers drag the same way there: nest a
group under another on its node, pull it back out, reorder it (the fused view
keeps its own order), Ctrl-drop (⌘-drop on a Mac) to clone, or drop it on the bin to delete. Nodes a
mode cannot use stay listed with the reason; the right-hand panel says what
carries over. Until this node is connected to a hub with a linked peer, move
to… and teleport to… stay in the menu greyed out, saying why (as the
node chips do); connect under ⚙ Fleet config → Hub. CLI: tclaude federation move-agent, tclaude agent clone,
tclaude agent morph, tclaude agent teleport.
The right-hand panel lists the shown nodes' profiles, roles, saved prompts, templates and sandbox profiles, one card per name. Picking another node's copy on a card acts on that node: Edit and Clone open the same editors and save there, and Rename… and Delete reach it too, while that node trusts this one unrestricted (locked with the reason otherwise). Open on NODE goes to that node's own dashboard.
Cloning on this node has one entry: send elsewhere → clone…, whose Clone mode continues in the clone dialog. The dialog can start the clone in another worktree, skip the conversation copy, and also copy the source's group ownerships (Copy group ownership, off by default). Ctrl-dragging (⌘-dragging on a Mac) an agent onto a group clones it into that group in one request: the clone and its new membership land together or not at all. In a peer's single-node view, the ⚙ clone item asks the peer instead.
Messages on several nodes¶
In a fused view, Messages shows the ticked nodes' mail with the same panes and
controls as one node's Messages: the folder and message filters, the bulk bar,
the pager and page size, the reader's headers, the footer toggles (retired,
empty and previous-generation agents) and the resizable panes. The node chips
above the folders narrow everything to one node (All nodes shows them all
again); a chip carries the node's unread notifications and its state when it
is not answering. All agent messages, Human notifications and Access
requests span the nodes in view, newest first (access requests oldest
first), each row carrying its node's pill. Under them each node has a foldable
section with its own folders: its all and human folders, its groups (expand
one for its members) and its agent folders. A merged folder pages through the
nodes' newest 500 messages each; pick one node to page further back. A peer's
mail is shown only if it grants you node.messages.read; otherwise its chip
and heading say "not shared". An unreachable node keeps its last page, marked
with its age; a node no longer trusted drops it. Bodies are shown as text.
Actions go to the node that owns the message. Mark read/unread on agent
messages (one, the selection, or an agent folder's mark all read) needs that
node's node.messages.manage; deleting needs the node to be this one or to
trust you unrestricted. A reply to an agent goes through its operator-message route
(message.direct). This node's human notifications have the same buttons as
in its own Messages (reply, focus, mark read/unread, download, delete), and
so do a peer's: reply opens the same dialog (text only) and goes to the peer
when it trusts you unrestricted. Opening a notification marks it read on its
node, as in each node's own Messages, wherever mark read/unread is allowed:
on this node, and on a peer that grants you node.messages.mark-read
(unrestricted trust holds it). Focus on a peer's notification opens the sending
agent's terminal here through the federation bridge. What a node withholds
stays in place, disabled, with a 🔒 saying what it needs. Their files preview, play and
download as usual, read from the peer under the same node.messages.read.
Access requests (approve once, deny) are answered here on this node and on
peers that trust you unrestricted; approving says exactly what it lets
through on that node. Anything a node does not allow from here
says so, and Open on NODE shows that node's own Messages. CLI:
tclaude federation human-inbox PEER (with reply and decide) and
tclaude federation action message --node NODE --agent ID --body TEXT.
The 🌐 marker¶
A group linked to federation peers carries a 🌐 after its header chips (a green
dot: a linked node is live). Click it for the links — a direct or pool grant,
or a route mirror — with what each allows and a jump to that node's dashboard.
CLI: tclaude federation links [--group NAME].
Cross-node group links¶
The inter-group link dialog's To row has a This node | Peer node 🌐
switch on nodes with cross-node links. Peer node lists only known peers you
trust at least limited and only the groups they share with you; an older peer
is listed but unavailable. With no hub connection the switch is greyed out with
the reason, and local links work as before. The note under the pickers says
what happens: if the peer granted you groups.link.accept for that group, the
link needs no prompt and shows connecting until the peer acknowledges this
exact edge; otherwise it sends a link request that the peer's operator approves
or declines within 24 hours. Also ask for the reverse link asks for the other
direction separately.
The Inter-group links list then gets This node and Peer side columns. Each row is one directed edge. A peer that is offline shows its side as unknown, with what it last reported, never as active or revoked. Deleting a cross-node edge stops delivery on this node immediately, including queued messages; a pending request reads cancel request instead. The 🌐 popover lists the same edges.
An incoming request appears in Messages → Access requests as a 🌐 link
request naming the exact edge and mode, with Approve, Approve + allow
future links into the group (which also grants that peer groups.link.accept
for it), and Decline. Approving authorizes only that edge, never broader
messaging from the peer. A request this node sent shows read-only, waiting for
the peer's operator.
Peer proposals¶
A proposal offers a peer several items in one go: groups of yours they may see (name, description and member count; the member list only when you tick include member list) and link edges between your groups and theirs, one direction or both (each direction is a separate edge). Open it with Propose… on a trusted peer in ⚙ Fleet config, or Propose several items… in the link dialog's Peer node mode. A preview lists exactly what is offered. Nothing changes on either node until the peer's operator accepts.
The proposal appears on both nodes in Messages → Access requests. The receiver ticks what to accept and gets Accept all, Accept selected or Decline all. Unticking member list on a share keeps only its name, description and count. Changing a link mode or sharing some of your own groups back sends a counter-proposal instead, and the turn passes to the other side. While the peer decides, the sender can Withdraw. When some edges were already accepted, the button reads Withdraw pending items: accepted edges stay until they are removed in Inter-group links. Each node applies only its own items. Accepting grants nothing beyond them.
Fleet administration (⚙ Fleet config)¶
⚙ Fleet config (Fleet at the end of the node row, then ⚙ Fleet config,
or "Fleet administration" in the command palette) manages this
node's federation. The identity bar at the top shows
this node's instance ID and full fingerprint (copy it to compare out of band),
the hub connection with Disconnect or Reconnect, installation… for this
node, and away cover: away… picks a trusted peer's operator (and an
optional end) who, while you are away, receives your agents' access requests
as they arise (and may answer each once; the first answer wins), every
message your agents send you, and waiting-session notices; return… ends
it. Peer operators' access requests are never
forwarded. settings… (or connect… before a hub is set) edits the hub
connection — URL, display name, a single-use invite, a CA file on this node —
and this node's labels, which automatic placement matches and peers with
node.read see. It also holds the fleet health notice policy
(tclaude federation nodes health): the defaults, or one trusted peer's own
policy, with offline/back, resource and failure notices and their thresholds
(empty = built-in default). Saving a peer's policy stops it following the
defaults. Its Identity section has Rotate identity…. Every action that widens trust, overwrites state or runs code confirms
first and says what will happen. Most pages name their CLI.
The pages, in order: Setup guide, Peers, Harnesses, Run scripts, Spawn requests, Invites & joining, Peer grants, Model gateways, Usage sharing, Profiles & pools, Offers, Jobs & repos, Moves, Boards, Audit and Hub.
- Setup guide — where Fleet opens until this node is joined to a hub,
trusts a peer and shares a group with it (the tab counts the steps done);
afterwards it is one tab away, for linking more nodes. Each step shows its
state, does the step in place and names its CLI. Any step, done or not,
opens from the list to read again; a joined node keeps the join
instructions under How joining works:
- Set up a hub (optional): how to run
tclaude hub serve(with TLS, or plain HTTP over loopback), where its one-time admin claim token is written, andtclaude hub invitefor each node's join code. Skip it when someone else runs the hub. - Become hub admin (optional): once joined, whether this node is an admin of its hub, or the same Claim hub admin… dialog as Hub for the claim token. Before joining it says to join first.
- Join a hub: paste the join code from the hub admin; the guide
shows what the daemon read from it (hub, space, invite expiry, the
SHA-256 of a certificate it trusts, and the hub it replaces) before
one Join confirmation. A hub address and a bare invite work too (a
pasted
tchi_invite moves to the invite field; a self-signed hub's CA file folds away), and this node's instance ID and fingerprint are there for an admin who admits nodes directly. A refused or unreachable hub is explained, and a refusal takes a new invite or join code in place. - Trust your peers: the nodes waiting in your spaces with their full fingerprints, and the same Trust… dialog as Peers; your own fingerprint to read to the other operator.
- Share groups: a peer, one of your groups and presets of ordinary
peer grants on it (Mail:
message.direct, roster and presence; Status:agents.status.read,sessions.read; Watch terminals:sessions.watch; Spawn workers:groups.members.spawn, cap 2), with what the peer already holds there left out. Peer grants has the rest. - Let agents use peers (optional): what each trusted peer shares with
this node, per group, which of your groups and agents already use it,
and Give access… for another group (every member) or agent. That
merges
peer=<peer>/<group>into their grants of the slugs that use it (tclaude agent permissions peer-reach add), keeping the rest; ✕ removes it again. A grant held for local use is refused with the way out rather than replaced.
- Set up a hub (optional): how to run
- Peers — while a peer views an agent terminal here, a panel on top shows
who watches or drives which agent; Disconnect… closes that view (the peer
can reopen it while any sessions.watch/attach grant covers that group, or at
once if it is unrestricted). Below: trusted peers (level, grants, pools) and hub-visible instances
waiting to be trusted. To trust one: Trust…, compare the fingerprint
shown in full with the other operator, tick the check, pick the level and
confirm. Unrestricted repeats that it grants every peer permission on all
groups, including ones created later. Restrict, unrestrict and untrust from
the row. A peer whose signing key is changing is marked next to
its fingerprint (and on its map card): new key pending is information
only — the successor waits out this node's detection window and is not yet
accepted; ⚠ competing keys needs explicit recovery, and its dialog shows
both fingerprints in full plus the
tclaude federation identity recover-peerpreview and the apply to run only after verifying the new fingerprint with the peer's operator. Rotating this node's key is under settings…; recovery stays in the CLI. - Harnesses — each node's harnesses in one table: version, ↑ when an
update exists, 🔑 when a login is present. Click a cell to install or update
(if workers are busy, choose to run now or when they are idle), or, for
login-file harnesses, to push your login to a peer (agents there then act as
you), back up or restore the node's login files. Update all… updates a
node's harnesses when its workers are idle. A peer needs to share
node.harnesses.read(and.install,node.credentials.receiveto change anything). - Run scripts — run one shell script on several nodes. Tick nodes (or
all online), write the script, set the timeout, Run and confirm. Each
node gets a pane with state, exit code, duration and output; full stdout
/ full stderr load the whole log, and Re-run on N failed… repeats it
only where it failed. A peer runs your script only if it granted you
node.execand turned on Accept remote scripts on its own Run scripts page — that switch is full remote code execution as the tclaude user, and the limits beside it cap each script's memory, cpu and processes. - Spawn requests — workers peers asked this node to start in its groups.
Its sub-tab counts the requests waiting for a decision, and a request's
notification in Messages has a review request… button that opens it.
Approve… starts the worker in that group as you (optionally overriding
name, profile, cwd, harness or model); Deny… declines with an optional
reason. A launch that never confirmed can be abandoned back to pending, but
the original worker may still appear late. Request a worker on a peer…
sends a brief to a peer's exported group, or to automatic placement (any
trusted node or a pool, with requirements; the dialog shows why each
candidate was chosen or skipped). A peer that granted you
groups.members.spawnon the group starts the worker right away. The outbox below shows delivery of the spawn requests and operator mail this node sent; decisions arrive in Messages. CLI:tclaude federation spawn-request,requests,outbox. - Invites & joining — Create invite… issues an enrollment token for a
node profile (uses, lifetime, and the trust to ask the joining node for,
which is only a request) and shows it once; revoke active tokens from the
list. To join a master: Join with a token…, pick the master, paste the
token, check both fingerprints in the preview, tick the check and
Enroll. Enroll gives the master restricted trust with no grants, whatever
the token asks for: the preview's "It asks for" line shows its requested
trust as a request, with a note pointing here when it asks for unrestricted. To give the master
control of this machine, for a worker node of your own fleet, use Become a
worker node… (the red button under Join): pick the master, paste the token
and Preview. Then tick exactly the permissions to give from the
filterable checklist (Sensitive ones are badged; nothing is preselected).
Choose, for each group permission, one group or every group including future
ones (a permission that needs a group, such as
agents.receive, takes one specific group); nothing is defaulted. Or tick Unrestricted, which disables the list. A red warning names everything that will be given, with each permission's own caution, and the button stays disabled until something is ticked and the master fingerprint you paste, compared with its operator over another channel, matches the previewed one. CLI:tclaude federation enroll,become-node. - Peer grants — pick a peer or a pool, see each grant with where it
applies (a group, or all groups including future ones, flagged) and what it
allows, Revoke… it, or add one: permission, group, cap, Grant….
Spawn and job grants have launch settings (profile, selectable
profiles, harness, model, directory, requester pays, job approval) that
decide how this node starts workers for the peer;
models.proxygrants take one gateway name or cover them all. Sensitive grants (spawning, attach,node.exec, …) say what they let the peer do. - Model gateways — this node's model gateways, which peers with a
models.proxy(or, for requester-paid workers,models.proxy.leased) grant use to send model requests charged to this node's provider account. See each gateway's models and limits — a gateway missing a model allowlist, a budget or a cap refuses every request and says so — turn one off or on, block or unblock a peer on it, or Turn off all…. Turning anything off revokes the matching leases at once, so requester-paid workers using them lose model access. Below that are the leases (Revoke… one) and a day's usage per gateway, peer and model. Add gateway…, Edit… and Remove… manage gateways themselves (provider, credentials, limits), and My Claude subscription covers running on your own login. CLI:tclaude federation models. - Usage sharing — Shared with you and You share: what subscriptions and gateways flow between nodes, with Ask for more….
- Profiles & pools — pools group nodes so one grant covers every member; add or remove members and open a pool's grants. Profiles bundle a trust level, pools and grants: Apply to peer… previews the plan, Make default… applies it to newly trusted peers. New profile… / Edit… edits a definition: trust level, pools, labels, requester-pays default and peer grants, with worker permissions, the teleport landing and the config bundle as JSON. Saving makes a new revision; peers it was applied to keep their settings until it is applied again.
- Offers — config and agent bundles peers offered this node, and the ones
it sent. Preview… shows what an incoming offer would change: per config
item new / overwrites yours / unchanged with security-relevant items marked
and a tick to leave each out, or for an agent its name, history and any
suspected credentials in it, plus placement and the values it needs here.
Apply… / Start agent… confirm what changes (a move or teleport says
the peer retires its source); Decline… deletes the payload. Offer my
config…, Offer an agent… and Offer a profile's config… send new
ones; flagged credentials are listed and need an explicit send-anyway.
CLI:
tclaude federation offers,offer-config,share-agent. - Jobs & repos — remote jobs: those peers sent here (⇠) and those this
node sent (⇢), with repo@ref, group, command and state. Approve… runs a
job a manual-approval
jobs.rungrant holds (jobs otherwise run on arrival); Cancel…, Resend… (same job ID, never runs twice), Acknowledge stopped… for a job this node lost track of, and Output once finished — each confirm says what happens. Run a job… sends one to picked nodes or an automatically placed one. Below, the repositories peers may run jobs in here: Allow…, Edit…, Disable…. Live output on a running job this node sent shows its output as it arrives (likejob run --follow), read every 2 s only while the dialog is open, Fleet is shown and the browser tab is visible; once the job ends it shows the stored output. CLI:tclaude federation job,repos. - Moves — agent moves and teleports in both directions (⇢ leaving, ⇠
arriving) with peer, group, state and expiry. Abandon… stops an outgoing
move that has not started retiring the agent here; the agent is not retired
(a copy the peer already made stays there). Freeze teleports… stops teleports leaving or landing
on this node until you allow them again; plain moves are not affected.
Move an agent to a peer… is
tclaude federation move-agent: it sends a local agent with its conversation history to a peer's receiving group, and the agent retires here once the peer confirms its copy is running (it leaves its groups and loses its grants here). The confirm says so, and keyboard focus starts on Cancel. - Audit — this node's federation activity, newest first: a peer acting here (⇠) or this node acting on a peer (⇢), with actor, target, group and outcome; refused or failed requests in red. Filter by peer and time window.
- Hub — for hub admins: claim, admins, admissions, invites, settings, health, logs, scripts and updates. See Federation.
The full federation model, grants and CLI are in Federation.
Boards (⚙ Fleet config → Boards)¶
With at least one joined board, the page opens on Browse content: everything posted to every board this
node is a member of, in one list. List is a dense table with a detail
pane; Cards shows the same items as cards with facets (kind, board,
publisher) that count and filter. The filter box matches name, description,
publisher and board in both views; it also takes kind:skill|config,
publisher:trusted|unknown|mine and board:NAME, which the facets and kind
tabs write for you. Sort by name, kind, publisher, board, version or last
update: click a List column header (ascending, descending, then posted
order), or use the Cards Sort dropdown and ▲/▼. The view and the sort are
remembered. Each item shows who signed it and whether that is a peer this node
trusts (trusted peer), this node, or an unknown publisher. An unknown
publisher's detail also says that a valid signature proves the version is
unaltered, not who runs that node. Selecting an item fetches and verifies it,
then lists every file; scripts and executables are flagged and open as text.
Install… on a config item is the board's import preview. On a skill it
offers four targets: a harness user skill directory, a group's default
directory (as a project skill under .claude/skills), a custom directory
(human-only: it must exist, symlinks and .. are refused, and the resolved
path is shown), or a plain browser Download. Every target but Download
previews the exact paths written and any overwrite first, and installs only
on confirm; keeping executable bits and overwriting are separate opt-ins.
Upload… posts to a board you can post to. Manage boards holds
everything below.
Boards share content with other nodes through the hub, without linking the nodes or giving anyone access to this machine. To join, paste an invite and press Join; to start one, type a name and press Create (you become its owner). Each board lists your role in plain words — owner, can post, can read — and its limits. Open a board to see its members. An owner can also invite someone who can read or post (the invite is shown once, with cancel invite…), change members' roles, remove members, and Change key… so that members removed earlier cannot read anything posted afterwards. Leave… ends this node's membership.
An open board also lists its shared config: signed, versioned roles,
profiles, sandbox profiles, templates and process templates its members
posted. Open… fetches and verifies a version on this node and shows its
files as text (or Download); Import… previews what would change in
this node's config — new, overwritten, security-relevant — and applies only
what you confirm, with any values it needs. Nothing on a board is applied
automatically. Versions… lists older versions and Keep… pins one (the
list then flags newer ones as update). Members who can post use
Post config… (whole sections, or named items such as roles/reviewer)
and New version…; anything that looks like a credential is refused.
Skills can also be posted as skills/NAME: one directory containing SKILL.md
and its supporting files. Post config… lets you select its local source
(Claude Code, shared ~/.agents/skills, or Codex home). The import preview lists every
file, marks scripts and executables security-relevant, and shows their
contents as text. Choose the destination skill root(s), preview again, and
confirm. Existing skills require overwrite confirmation. Executable bits are
removed unless you explicitly confirm preserving them; scripts can still be
invoked through an interpreter. Symlinks and special files are refused. Group destinations
install project skills under the group's default directory at
.claude/skills/NAME; custom destinations must be existing absolute directories
without symlink components or parent traversal. The preview shows the resolved
path before confirmation. A verified archive download contains the skill files
(or bundle.json for configuration items), with executable bits stripped
unless explicitly confirmed.
Post to… (on an item or one of its versions) posts that version, unchanged
and still signed by its author, to another board you can post to. An
item whose signed details cannot be verified shows the error and cannot be
opened or imported. The hub decides who is a member: a dishonest hub
operator could block a board or keep a removed member getting new posts, but
cannot read anything or fake a post, so use a hub you trust. Hub admins
holding hub.boards.manage see Boards on the Hub page to freeze, limit
or delete boards; they never see content or keys. CLI:
tclaude federation boards … and tclaude federation hub boards ….
When an item you keep has a newer version on its board, the Boards tab
shows a count, and the page lists those items with Open board. Tick
"Also leave a note in Messages…" to get one Messages note per new version
(off by default). Neither fetches nor imports anything. CLI:
tclaude federation boards updates [--refresh] [--notify on|off].