Content boards¶
Share skills and configuration with people you don't grant peer access to.
Content board membership¶
Content boards use a separate hub connection at /v1/boards/connect. Joining
with a board invitation binds membership to the joining instance's key; it does
not admit that instance to the fleet, assign peer-visible spaces, pair it with
other members, or grant access to any member's machine. Board connections accept
only signed board RPCs. Hub administration, envelopes, directories and relay
streams remain unavailable, even when the hub uses open fleet admission.
Owners manage membership and invitations; publishers may publish and readers may browse and pull. Removing or demoting the last owner is refused. Invitations are single-use, expire after at most seven days, and may grant only reader or publisher membership. Keep the invitation private: its token includes the secret needed to unwrap the board key. Neither bearer tokens nor plaintext board keys are stored by the hub. A consumed invitation can recover an interrupted join only for the same instance while its membership still exists.
The hub stores encrypted key envelopes and ciphertext. A key rotation wraps a new epoch key separately to each current member's instance key, after verifying that member's proof of the current key, and invalidates unused invitations from the previous epoch. Removed members immediately lose hub access; rotation protects future publications. Previously obtained keys or plaintext cannot be revoked. Remaining members keep access to retained older key epochs. Lost owner keys require another owner or a new board; hub admins cannot recover content keys. A dishonest hub operator could deny service or keep a removed member in the loop for new content; it cannot read content or forge publisher-signed items, so pick a hub you trust.
Use tclaude federation boards ls (with list retained as an alias), create --name NAME, join --token TOKEN,
show --board ID, members --board ID, invite --board ID --role reader --ttl 1h,
revoke-invite --board ID --token-id HASH, set-member --board ID --instance ID
--role publisher, remove-member --board ID --instance ID, rotate-key --board
ID, and leave --board ID. Configure the invitation's hub URL first; joining
never enables a peer connection. Dashboard and CLI routes under
/api/federation/boards and /v1/federation/boards require local human authority
and are never forwarded through peer view.
Hub admins with hub.boards.manage can list, freeze, limit or delete boards using
tclaude federation hub boards list|set|delete --board ID. This capability does
not reveal keys or plaintext. Default limits are 100 boards per hub, 100 members
per board, 100 outstanding invitations, 256 MiB of ciphertext plus encrypted
key/invitation metadata, and 1,000 blobs per board. Ciphertext objects are
bounded at 16 MiB plus encryption overhead. Pending uploads consume quota;
failed uploads release their reservation. Ready, unpinned blobs expire after
30 days, and abandoned upload reservations after one hour; startup cleanup
reaps expired objects and old orphan files. A quota reduction never silently
ejects members or removes pinned objects. Publication/import surfaces follow
in the item slice: membership alone never installs content or runs commands.
Board items are immutable, publisher-signed configuration versions. The hub stores only encrypted payloads and encrypted descriptive metadata; re-publishing an unchanged version preserves its original publisher signature. Phase 1 shares portable configuration sections such as roles, profiles and process templates, not broad local config or default permissions. Credential scanning runs before publication and again after decryption on the receiver. Suspected credentials must be excluded before publication.
Skills are a separate signed item kind. Publish one directory with
tclaude federation boards publish --board ID --name NAME --only skills/NAME.
The source must contain SKILL.md under a known user skill root:
~/.claude/skills, ~/.agents/skills, or $CODEX_HOME/skills (default
~/.codex/skills). If several roots contain that name, select
--skill-root claude|agents|codex. Symlinks and special files are refused;
there are at most 512 files and the encoded bundle must fit the existing
16 MiB Board item limit. Credential scanning covers every file.
Skill preview/import use --skill-target claude,agents,codex (select the roots
you want) instead of config selectors. Preview lists files and script text,
flagging shebangs, script extensions and executable bits as security-relevant.
Executable bits are stripped unless --preserve-executable is explicitly set.
Existing skills require --replace. Import requires the preview token with
exactly the same roots and confirmations; target changes invalidate it.
Group targets use --skill-target group:NAME and install project skills into
the group's current default directory at .claude/skills/NAME. The preview
shows the resolved destination. A custom skill root uses --skill-target custom
--custom-dir /absolute/existing/directory; it must exist, with no .. or
symlink in any path component. Custom targets are human-only. Target paths and
root identities are bound to the single-use preview token; a changed group
default directory or custom root requires another preview.
After fetching, GET /api/federation/boards/BOARD/items/ITEM/versions/VERSION/archive
(or /v1/federation/boards/.../archive) streams a verified tar.gz download.
Skills contain NAME/SKILL.md and supporting files; config items contain
bundle.json. Executable bits are stripped unless ?preserve_executable=1
is explicitly requested. The existing /download still returns the JSON
transfer bundle.
Catalog rows expose updated_at (UTC) and seq as hub-reported sorting data,
outside signed receipts. An optional description from skill frontmatter is
independently publisher-signed inside the existing encrypted metadata, bound
to the item, version and payload hash. Older daemons ignore this extension and
continue verifying the original manifest and receipt unchanged. Missing or
invalid descriptions are omitted without hiding valid content. New re-posts
preserve the description; older re-posters may omit it. Older hubs omit the
sorting fields, so newer clients display them as unknown.
Installing a skill does not execute any of its files. Agents may later follow its instructions or run scripts, including through an interpreter without an executable bit, so inspect them before confirming.
Agent snapshots are a third item kind, agent-snapshot: a snapshot PAF
encrypted to named members only, with a hard expiry (7 days by default, at
most 30) and up to four blobs. Use tclaude agent snapshot share and
tclaude agent snapshot board ls|fetch|preview|import|rm; see
PAF: Sharing a snapshot on a Board.
Use federation boards publish --board ID --name NAME --only roles/NAME,
items --board ID, and versions --board ID --item ITEM. Updates use
publish --item ITEM --parent VERSION; a stale parent is refused. pin --board
ID --item ITEM --version VERSION keeps a selected version through retention;
item listings show latest_version, pinned_version and update_available.
boards updates (GET /api/federation/boards/updates, /v1 alike) lists
every kept item, across this node's boards, whose latest version differs from
its pin: {updates:[{board,board_name,item,name,pinned_version,latest_version}],
notify,checked_at,error}. It reuses a check up to five minutes old; --refresh
(?refresh=1) checks again, at most every 30 seconds. boards updates --notify
on|off (PUT {notify}, stored as federation.board_update_notify, default off)
makes the daemon check every 15 minutes and leave one Messages note per newly
seen version. The very first check on a node only records what it finds;
after that every new version gets one note, including versions posted while
the daemon was down (announced versions are kept in the data directory for 180
days). A failed check is retried after 30 seconds rather than cached, one
unreadable board does not hide the others, and keeping a version, leaving or
deleting a board refreshes the list. The check reads catalogs and pins only:
nothing is fetched or imported. These routes
are human-only and never served through peer view.
Re-publication uses publish --board DEST --from-board SOURCE --from-item ITEM
--from-version VERSION and retains exact original bytes and provenance.
fetch, contents, download, preview and import take --board ID --item
ITEM --version VERSION. Fetch verifies and scans into a private spool; it never
imports. Contents accepts --path, --offset and --max-bytes for bounded
inspection. Download requires --file PATH and never overwrites an existing
file. Preview accepts the existing --only, --skip, --set NAME=VALUE and
--replace choices. Import requires the preview's --preview-token with the
same choices. Tokens expire after ten minutes and are single-use; changed local
configuration requires a fresh preview. There is no automatic apply.
The matching human-only /api/federation/boards/{board}/items and /v1 routes
provide list/publish, /{item}/versions, /{item}/pin, and
/{item}/versions/{version}/{fetch,contents,download,preview,import}. Downloads
support HEAD and use attachment disposition, nosniff and a sandbox CSP. Board
blob transfer uses the separate /v1/boards/stream connection with the existing
authenticated stream framing, shared hub bandwidth limits, bounded sizes and a
five-minute deadline. Board-only connections remain refused at every fleet and
hub-admin entry point, including on this stream endpoint.
federation boards --help lists action subcommands. Each action's help shows
only its applicable flags and marks the required ones. boards invites --board
ID lists owner-visible invitation IDs, roles, epochs, expiry times and redeemed
instances; it never returns bearer tokens or sealed key packages. The matching
human-only local GET /api/federation/boards/{board}/invites and /v1 routes
return {invites:[...],next_cursor} with at most 50 rows per page.
federation moves ls prints a table; use --json for the full response.
Remote file downloads require the stable agt_…@peer address shown by
federation sessions, rather than a session display name.
Board cleanup and project file browsing¶
Owners can permanently delete a board with tclaude federation boards delete --board ID (dashboard API: DELETE /api/federation/boards/ID). Deletion removes hub membership, invitations, keys and item metadata; it cannot erase copies members already pulled. The dashboard should confirm deletion before calling it.
tclaude federation file ls agt_…@peer [dir] lists one project directory level through a temporary pinned terminal viewer, with the same watch/attach and sessions.files.read checks as file get. It examines at most 100 entries, omits secret paths, symlinks, special files and files above the download cap, and reports when the listing is capped. Use a narrower directory to see more. No recursive scan is performed. A browser with a live viewer uses GET /api/federation/terminal-file?terminal=…&viewer=…&path=DIR&list=true; the JSON response contains entries (path, kind, size) and truncated.
federation boards ls, items, invites, federation file ls and federation hub status show compact tables by default; pass --json for the unchanged structured response. Short-lived board RPC connections are deliberately isolated from fleet pairing and appear only in hub Debug logs.