spoke-setup
Skill4 starsChanged 4 months agoMITView on GitHub
Add this machine to an EXISTING Cos as a SPOKE — a stateless client of the hub. It flips COS_DEVICE_ROLE=spoke, points BOARD_URL at the hub's tailnet URL, and wires ONLY the board-facing MCP wrappers (board, calendar, and any enabled add-on wrappers) so Claude Code + Cowork on this machine drive the hub's board over Tailscale. A spoke runs NO local board, NO store, NO backups (the hub owns all of that); its local store guard refuses writes by construction. Use when adding a second (or third) device to a Cos setup, "join my other machine to Cos", "set up my laptop as a spoke", when someone hands you a cos-join:// string, or when a machine should drive the hub's board with a local agent (Claude Code/Cowork) without running its own board (to merely view the board, no spoke is needed — just a browser over the hub's Tailscale URL). NOT for the first machine (that's a HUB — use cos-setup).
- Reads credentials
In this repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- mcp/CLAUDE.mdCLAUDE.md
- add-an-addonSkill
- backup-recoverySkill
- body-mcp-setupSkill
- cos-setupSkill
- cos-upgradeSkill
- debug-cowork-mcp-issuesSkill
- fitness-mcp-setupSkill
- guard-setupSkill
- hub-handoverSkill
- mcp-bridge-setupSkill
- nutrition-mcp-setupSkill
- openwhispr-mcp-setupSkill
- setup-vaultSkill
- voice-operationsSkill
- whatsapp-mcp-setupSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 121
A write appears on the hub: create a test case from this spoke (browser or MCP).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Spoke setup — join this machine to an existing Cos hub
A spoke is a machine that uses an existing hub's board over the network instead of running its
own. Its board-facing MCP wrappers (board, calendar, enabled add-ons) point at the hub's
BOARD_URL; there is no local board, no cases.json, no backups here — the hub owns all state.
The store's role guard (SpokeRoleError) refuses any local write, so a spoke can never fork the
single source of truth.
This is NOT the first-machine path. The first machine is a HUB — run
cos-setup. Use this skill only to add a machine to a Cos that already exists.
Do you actually need a spoke? If you only want to VIEW / use the board UI from this machine, you need NOTHING here — open the hub's
tailscale serveURL (https://<hub>.<tailnet>.ts.net, portless HTTPS 443) in a browser and you get the full read/write UI (zero setup; the browser writes through the same HTTP API). Runspoke-setuponly to let Claude Code / Cowork ACT on the board from this machine with local MCP tools. Why a spoke and not just the URL: Cowork accepts only local stdio MCP servers (never a remote HTTP MCP over the tailnet), so a thin local wrapper pointed at the hub is the only way to hand a local agent those tools — a browser can't. VIEW it → browser; ACT with an agent → spoke.
What you need first — the join string
On the hub, open the board's Devices panel → Add a device, or run
node scripts/join-blob.mjs on the hub. Either gives a cos-join://v1?hub=…&schema=… string. It
carries the hub's tailnet URL + its store schemaVersion (+ an optional backup-repo ref) — addresses
and expectations, no secrets, so it neither expires nor needs protecting.
Also required: Tailscale installed + logged in on BOTH machines (the hub and this spoke) on the
same tailnet, and the hub serving its board over the tailnet (tailscale serve --bg 3000, so the hub
answers at https://<hub>.<tailnet>.ts.net).
Step 0 — Tailscale reachability + hub handshake (do this FIRST)
Confirm this machine can reach the hub over the tailnet before writing any config. Substitute the
hub= value from your join string:
HUB="https://<hub>.<tailnet>.ts.net" # the join string's hub= value
curl -fsS --max-time 5 "$HUB/api/healthz" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);console.log("hub role:",j.role,"deviceId:",j.deviceId,"schema:",j.schemaVersion)})'CHECKPOINT — the hub answers with role: hub and a schemaVersion. If curl can't reach it: check
tailscale status on both machines (same tailnet, both up) and that the hub ran tailscale serve.
Cowork reach preflight (spawned-child networking): Claude Cowork Desktop spawns its MCP wrappers as child processes; confirm a child can reach the hub the way a wrapper will, BEFORE wiring Cowork. On macOS:
/Applications/Claude.app/Contents/Helpers/disclaimer "$(command -v node)" \
-e "fetch(process.env.HUB+'/api/healthz').then(r=>console.log('reach:',r.status)).catch(e=>console.log('BLOCKED:',e.cause?.code||e.message))" HUB="$HUB"CHECKPOINT — prints reach: 200. If it prints BLOCKED, Cowork's sandbox is refusing the tailnet
host (rare — see the Gotchas); the browser + Claude Code paths still work, so continue but skip the
Cowork wiring step.
Step 1 — write this machine's spoke config
config/cos.env is machine-local (never in the backup scope), so a spoke writes its OWN. Set the
role to spoke and BOARD_URL to the hub — the loader REFUSES spoke + a localhost BOARD_URL.
source "$(git rev-parse --show-toplevel)/config/load-config.sh" # seeds defaults; safe pre-cos.env
# Append (or edit) the spoke keys in config/cos.env:
{
echo 'COS_DEVICE_ROLE="spoke"'
echo "BOARD_URL=\"$HUB\"" # the hub's tailnet URL from the join string
echo "COS_DEVICE_ID=\"$(node -e 'console.log("spoke-"+require("crypto").randomBytes(4).toString("hex"))')\""
} >> "$REPO_ROOT/config/cos.env"
# Re-source and verify the loader accepts the spoke config (it validates role + the spoke/localhost rule):
source "$REPO_ROOT/config/load-config.sh" && echo "role=$COS_DEVICE_ROLE BOARD_URL=$BOARD_URL"CHECKPOINT — the loader prints role=spoke and a non-localhost BOARD_URL with no error. (An
error here means the role is misspelled or BOARD_URL is still localhost — fix config/cos.env.)
Step 2 — install ONLY the board-facing wrapper bridges
The generators are role-scoped: on a spoke they install just the board-facing wrappers (their
CRM_BASE_URL resolves to the hub's BOARD_URL), never the hub-only services (vault, guard, the
sidecars, the board app, backup). Install the wrappers this spoke should have — always board +
calendar; add any add-on wrapper the hub has enabled (nutrition, fitness, body):
source "$(git rev-parse --show-toplevel)/config/load-config.sh"
node "$REPO_ROOT/scripts/gen-launchd.mjs" --install board calendar # + nutrition/fitness/body if enabled on the hub
node "$REPO_ROOT/scripts/gen-mcp-json.mjs" # regenerate REPO/.mcp.json (committed; CI-checked — never hand-edit)Naming a hub-only service here (e.g.
vault) is a LOUD error by design — a spoke does not run it.
CHECKPOINT — lsof -nP -iTCP:$BOARD_BRIDGE_PORT -sTCP:LISTEN shows the board bridge listening on
127.0.0.1, and curl -s http://127.0.0.1:$BOARD_BRIDGE_PORT/mcp answers (the bridge is up; it proxies
to the hub).
Step 3 — wire Claude Cowork Desktop (skip if the Step-0 preflight was BLOCKED)
source "$(git rev-parse --show-toplevel)/config/load-config.sh"
node "$REPO_ROOT/scripts/gen-cowork-config.mjs" board calendar # + the same add-on wrappers as Step 2Then ⌘Q + reopen Cowork so it re-reads the config. The wrappers' CRM_BASE_URL points at the hub.
CHECKPOINT — in Cowork, get_device_status (board MCP) returns the HUB's device id + role: hub
(you're driving the hub). If Cowork can't spawn the wrapper, the Step-0 preflight would have caught it.
Step 4 — verify end-to-end
- Browser: open
$BOARD_URL— the hub's board loads over the tailnet, with a "Connected to<hub>" chip bottom-right (the spoke chip). - Claude Code:
mcp__board__get_device_statusreturns the hub's identity;mcp__board__get_treeround-trips real cases. - A write appears on the hub: create a test case from this spoke (browser or MCP); it shows up on the hub's screen (SSE) — one board, two windows.
- The store guard holds:
cd board && npm run devREFUSES on this spoke (predev spoke-abort), and a directnpx next devwrite attempt would 503 (spoke-role-refusal) — a spoke never serves a local board.
Manage
- Which add-on wrappers a spoke wires — only the board-facing ones the hub has ENABLED.
vault,guard,search,whatsapp,openwhisprare hub-only (the spoke reaches their data through the hub's board where applicable). Add/remove a wrapper by re-running Steps 2–3 with its name. - Warm-standby tier (optional): a spoke can keep a pulled clone of the backup repo + the shared recovery key so hub-failure recovery is "restore + flip role" in minutes. That's a separate opt-in (see the backup-recovery skill); this skill does NOT make the spoke a backup producer.
- Promote this spoke to hub (planned failover / handover): that's the
hub-handoverceremony (a later skill), not spoke-setup — it involves restoring the store and flipping the role back to hub.
Gotchas
- A spoke has NO local board/store/backup.
COS_DEVICE_ROLE=spoke+BOARD_URL=<hub>is the whole contract; the store guard enforces read-only locally. Never runcos-setupStep 0 (the seed) on a spoke — that's the seed-over-live-data footgun, and there's nothing local to seed anyway. - Address the hub by its
ts.netname, never a LAN IP. A LAN/RFC1918 address can hit a silent macOS Local-Network-privacy block for Desktop-spawned children; the tailnet MagicDNS name (or a 100.x address over plain HTTP) is outside that gate. .mcp.jsonis committed + CI-checked — regenerate it withgen-mcp-json.mjs, never hand-edit. On a spoke it stays byte-identical to the hub's (the bridges are still localhost; only the wrappers'CRM_BASE_URLdiffers, which lives in the plist env, not.mcp.json). The hub-only entries it lists (vault/guard/whatsapp/openwhispr) simply show as unreachable on a spoke — cosmetic, documented.- Cowork spawned-child reach is validated in Step 0; if it's blocked, the browser + Claude Code paths are fully functional — Cowork on a spoke is a convenience, and the daily routines run on the HUB's Cowork by design.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

