Pairing, links & tokens — untangled.

The broker lives on Tony's machine

When Tony starts Sys-Buddy, the broker (the little server that coordinates everything) runs on his own computer at localhost:8787. "localhost" just means "this very machine." (8787 is just the default MCP port — the broker can run on any port Tony picks; the examples below use 8787.)

Here's the whole problem in one picture — localhost is useless to Peter, because on Peter's laptop, "localhost" means Peter's laptop:

TONY'S LAPTOP                    PETER'S LAPTOP
  broker → localhost:8787          Peter types localhost:8787
  ✅ "that's me, here it is"        ❌ reaches HIS OWN laptop,
                                      not Tony's. Nothing there.

So Peter needs some address that leads to Tony's machine specifically. Everything else here is just "how does Peter get that address, and how does his request travel there."

Address vs token: where vs who

This is the single most important idea, and it unlocks the rest. Two totally different jobs, done by two different things:

When Peter pairs, his connect command literally spells out both halves:

claude mcp add --transport http sys-buddy \
  http://100.101.102.103:8787/mcp \        ← WHERE (Tony's broker)
  --header "Authorization: Bearer PETER_TOKEN"  ← WHO (it's Peter)

Tony and Peter dial the same broker address, but each request is stamped with a different token — so the broker always knows who's who. A leaked address alone is harmless: no token → 401, door stays shut.

How Peter's request actually travels

Peter's Claude agent makes the network call — same as if Peter typed curl in a terminal. Here's the key idea: Claude doesn't do the networking itself. It hands the request to the operating system and says "please deliver this." The OS decides the route.

So the real question is: does Peter's OS know a route to Tony's machine? For an ordinary public web address, yes — every machine already knows how to reach the public internet. For a private address, it only works if something has taught the OS that route:

Peter's Claude:  "OS, connect me to Tony's broker"
        │
        ▼
 Peter's OS:  "do I have a route to that address?"
        │
   ┌────┴────────────────────────────────┐
   │ public address (ngrok) →            │
   │   "sure — it's on the internet,      │
   │    I already know the way." ✅        │
   ├─────────────────────────────────────┤
   │ private address + Tailscale on →    │
   │   "that's Tony's machine on our       │
   │    tailnet — routing it there." ✅    │
   ├─────────────────────────────────────┤
   │ private address, no Tailscale →     │
   │   "no route. request dies here." ❌   │
   └─────────────────────────────────────┘

The token proves who Peter is, but without a route his machine can't reach Tony at all — so he never even gets to show the token. Supplying that route is the whole job of the two paths: ngrok gives Tony a public address (nothing for Peter to install), while Tailscale builds a private network both machines join. That's the fork — pick either path from the roster to see it in full.

Three addresses, one broker

Same broker every time; only the address out front changes depending on the road:

ngrok makes a public address — every machine already knows how to reach public addresses, so Peter installs nothing. Tailscale makes a private address that only works between machines running Tailscale. That's the whole trade-off.

Two doors: act, and watch

The broker answers at two paths. Once Peter's machine can reach the address, any program on it — Claude and his web browser — can use both:

Peter's Claude  → http://100.101.102.103:8787/mcp       ← the tool door (act)
Peter's browser → http://100.101.102.103:8787/ui?v=…    ← the dashboard (watch)
                  └──────── same broker, same address ────────┘

Peter opens the dashboard in his browser at the same address. The ?v= viewer token proves he's allowed to watch (read-only). Address gets the browser there; token says what he may do.

Is the invite link also the dashboard?

No — but redeeming it produces one. When Peter redeems the sb1_ invite, pairing hands back three things: