# Relay Discovery and Pairing UX
Status: Draft
The relay transport works, but connecting two instances requires exchanging PSK codes and IP addresses manually. This document specifies four discovery mechanisms — from zero-config LAN to distributed teams — designed to make pairing as simple as Bluetooth.
## The Problem
Current pairing flow:
```
# Machine A # Machine B
claudectl relay pair
# → PAIR CODE: a3f2-9b1c-d4e5-f678
# → "They should run: claudectl relay accept a3f2-9b1c-d4e5-f678 machineA-x7f2"
claudectl relay accept a3f2-9b1c-d4e5-f678 machineA-x7f2
claudectl relay serve
claudectl relay connect 192.168.1.50:9847
```
Four friction points:
1. You need to know the other person's IP address
2. You need to copy a 19-character code between machines
3. You need to run the commands in the right order
4. There's no way to see "who else is using claudectl near me"
## Design Principle
Each mechanism solves discovery at a different radius:
| LAN Broadcast | Same network | Auto-discover, manual approve | Zero config |
| Project Peers | Same git repo | Committed peer list | One-time setup |
| Invite Link | Anywhere | Shared URL with embedded PSK | Copy one link |
| Tailscale | Tailnet | Tailscale identity = trust | Zero config |
All four are additive and optional. The existing manual pair/accept/connect flow remains the fallback.
---
## Mechanism 1: LAN Broadcast Discovery
**The idea:** When relay is enabled, claudectl periodically broadcasts a UDP announcement on the local network. Other instances see it and offer to pair.
### How it works
```
Machine A starts relay:
→ Sends UDP broadcast to 255.255.255.255:9848 every 10s
→ Payload: {"identity": "laptop-a3f2", "port": 9847, "version": "0.36.0"}
Machine B starts relay:
→ Listens on UDP :9848, receives A's announcement
→ Shows in TUI: "Discovered: laptop-a3f2 (192.168.1.50:9847) — press 'P' to pair"
→ User presses P (or runs CLI command)
→ B generates a PSK, sends a pairing request via TCP to A
→ A's TUI shows: "Pair request from desktop-b7c1 — approve? (y/n)"
→ User on A presses y
→ Both sides store the PSK, connection established
```
### CLI flow
```bash
# Discover nearby instances (one-shot scan)
claudectl relay discover
# → Found 2 claudectl instances on LAN:
# → laptop-a3f2 192.168.1.50:9847 v0.36.0
# → ci-runner-9d1e 192.168.1.101:9847 v0.36.0
# Pair with a discovered instance (interactive)
claudectl relay pair-with laptop-a3f2
# → Sending pair request to laptop-a3f2...
# → Waiting for approval on the remote side...
# → Paired! Connected to laptop-a3f2.
```
### TUI flow
When `relay.lan_discovery = true`:
- The status bar shows `LAN: 2 peers nearby`
- Pressing `P` opens a discovery overlay:
```
┌─ Nearby Peers ─────────────────────────────────────┐
│ ● laptop-a3f2 192.168.1.50 v0.36.0 [Pair] │
│ ● ci-runner-9d1e 192.168.1.101 v0.36.0 [Pair] │
│ │
│ Already paired: │
│ ✓ desktop-b7c1 192.168.1.42 connected │
└─────────────────────────────────────────────────────┘
```
- Selecting a peer and pressing Enter sends a pair request
- The remote side gets a notification in their TUI
### Protocol
**Announcement (UDP broadcast, every 10s):**
```json
{"type": "announce", "identity": "laptop-a3f2", "port": 9847, "version": "0.36.0", "paired_count": 1}
```
**Pair request (TCP, after user initiates):**
```json
{"type": "pair_request", "from": "desktop-b7c1", "psk_proposal": "<hex-encoded-canonical-psk>"}
```
**Pair response (TCP):**
```json
{"type": "pair_response", "from": "laptop-a3f2", "status": "approved"}
```
The PSK is generated by the initiator and sent encrypted — but since we don't have TLS, the pair request includes the PSK in plaintext over TCP. On a trusted LAN this is acceptable. For untrusted networks, use the manual pair code flow or invite links.
### Security considerations
- Announcements are read-only — they don't contain secrets
- The pair request contains the PSK, so it must travel over a trusted network
- Each pair request requires explicit approval on the receiving side
- The discovery can be disabled: `relay.lan_discovery = false`
- Announcements include no sensitive data (just identity, port, version)
### Config
```toml
[relay]
lan_discovery = true # enable UDP broadcast discovery
lan_announce_interval = 10 # seconds between announcements
lan_broadcast_port = 9848 # UDP port for announcements
auto_approve_lan = false # if true, skip approval prompt (team LAN)
```
### Implementation notes
- Uses `std::net::UdpSocket` — no new dependencies
- Broadcast socket binds to `0.0.0.0:9848` with `SO_BROADCAST`
- Received announcements are cached for 30s (3 missed = stale)
- The TUI discovery overlay reuses the help overlay rendering pattern
---
## Mechanism 2: Project Peers (Git-based)
**The idea:** Store a list of team peers in the project repo. When someone clones the repo and runs claudectl, they automatically know who to connect to.
### How it works
```
# One-time: team lead sets up the peer list
claudectl relay project-init
# → Created .claudectl/peers.toml with your identity
# Commit it to the repo
git add .claudectl/peers.toml && git commit -m "add claudectl relay peers"
# When teammates clone and run claudectl:
# → claudectl reads .claudectl/peers.toml
# → Shows: "Team peers: laptop-a3f2 (not paired), ci-runner-9d1e (not paired)"
# → Offers to pair with each one
```
### File format: `.claudectl/peers.toml`
```toml
# Team claudectl relay peers
# Add your identity with: claudectl relay project-add
# Connect with: claudectl relay project-connect
[[peers]]
identity = "laptop-a3f2"
name = "Barada's laptop" # human-friendly name
addr = "192.168.1.50:9847" # last known address (optional)
tailscale = "laptop.tail1234.ts.net" # Tailscale hostname (optional)
[[peers]]
identity = "ci-runner-9d1e"
name = "CI runner"
addr = "10.0.0.42:9847"
```
### CLI flow
```bash
# Add yourself to the project peer list
claudectl relay project-add
# → Added laptop-a3f2 to .claudectl/peers.toml
# → Commit this file to share with your team.
# Show project peers and connection status
claudectl relay project-peers
# → PROJECT PEERS (.claudectl/peers.toml):
# → laptop-a3f2 Barada's laptop ● connected
# → ci-runner-9d1e CI runner ○ not paired
# Connect to all project peers (pairs if needed)
claudectl relay project-connect
# → Connecting to ci-runner-9d1e at 10.0.0.42:9847...
# → Pair request sent. Waiting for approval...
# → Connected!
```
### How pairing works
When `project-connect` finds an unpaired peer:
1. It looks up the peer's address from the TOML
2. Connects via TCP and sends a pair request (same as LAN mechanism)
3. The remote side sees the request and approves
4. PSK is established, connection persists
If the address is stale or wrong, it falls back to LAN discovery or prompts for the correct address.
### Security
- The `.claudectl/peers.toml` file contains no secrets — just identities and addresses
- Pairing still requires explicit approval on the remote side
- The file can be `.gitignore`d if the team prefers not to commit it
---
## Mechanism 3: Invite Links
**The idea:** Generate a self-contained URL that encodes the PSK, identity, and address. Share it via Slack, email, or QR code. The recipient clicks it and is paired instantly.
### How it works
```bash
# Generate an invite link
claudectl relay invite
# → Your relay invite link (valid for 24 hours):
# →
# → claudectl relay join cctl://laptop-a3f2@192.168.1.50:9847/k/a3f29b1cd4e5f678
# →
# → Or scan this QR code:
# → ██████████████
# → ██ ██
# → ...
# Recipient runs the join command
claudectl relay join cctl://laptop-a3f2@192.168.1.50:9847/k/a3f29b1cd4e5f678
# → Connecting to laptop-a3f2 at 192.168.1.50:9847...
# → Authenticated!
# → Paired with laptop-a3f2.
```
### Link format
```
cctl://<identity>@<host>:<port>/k/<psk-code>
```
Example: `cctl://laptop-a3f2@192.168.1.50:9847/k/a3f29b1cd4e5f678`
Components:
- `cctl://` — scheme (claudectl link)
- `laptop-a3f2` — remote peer identity
- `192.168.1.50:9847` — address to connect to
- `/k/a3f29b1cd4e5f678` — the PSK code (same format as `pair` output, dashes stripped)
### CLI flow
```bash
# Generate invite
claudectl relay invite [--ttl 24h] [--json]
# Accept invite
claudectl relay join <link>
# The join command:
# 1. Parses the link
# 2. Derives the canonical PSK from the code
# 3. Stores the PSK for the remote identity
# 4. Connects to the address
# 5. Authenticates with HMAC challenge-response
# 6. Done — paired and connected
```
### Advantages over manual pairing
- **One command, one side.** The recipient runs one command. No back-and-forth.
- **Self-contained.** The link has everything: identity, address, PSK.
- **Shareable.** Paste in Slack, email, or print as QR code.
- **Expirable.** TTL ensures old links don't work forever.
### TTL enforcement
The invite link itself doesn't expire (it's just data). TTL is enforced by:
1. Storing the generated PSK with a `created_at` timestamp
2. During auth, checking if the PSK was created within the TTL window
3. If expired, the listener rejects the handshake with `status: "expired"`
### QR code
The link is short enough for a QR code (under 80 characters). claudectl can render the QR in the terminal using Unicode block characters — no external dependencies. This is particularly useful for pairing a laptop with a CI server or remote machine where you can see the terminal.
```bash
claudectl relay invite --qr
# → Renders a scannable QR code in the terminal
# → (The other machine runs: claudectl relay join <scanned-text>)
```
---
## Mechanism 4: Tailscale Auto-Discovery
**The idea:** If both machines are on the same Tailnet, use the Tailscale API to discover peers automatically. Tailscale provides stable IPs, encryption, and identity — solving discovery, auth, and transport in one shot.
### How it works
```bash
# Enable Tailscale discovery
# In .claudectl.toml:
# [relay]
# tailscale = true
# claudectl detects Tailscale is running:
# → Queries `tailscale status --json` for peer list
# → Filters for machines running claudectl (port probe or tag-based)
# → Auto-connects using Tailscale identity as the trust anchor
```
### Detection
1. Check if `tailscale` CLI is available
2. Run `tailscale status --json` to get the peer list
3. For each peer, probe port 9847 to see if claudectl relay is running
4. If found, connect using a Tailscale-derived PSK (HMAC of both Tailscale node IDs + a shared constant)
### Trust model
Tailscale already provides identity and encryption. The HMAC-based PSK derivation means:
- No manual pairing needed — trust is inherited from the Tailnet
- Each pair of nodes gets a unique PSK (derived from their node IDs)
- An attacker would need to compromise the Tailnet to impersonate a peer
### Config
```toml
[relay]
tailscale = true # enable Tailscale auto-discovery
tailscale_tag = "tag:claudectl" # only connect to peers with this ACL tag
tailscale_probe_interval = 60 # seconds between peer probes
```
### Why this works well
- Zero manual pairing for teams already using Tailscale
- Stable IPs across roaming, NAT, etc.
- Built-in encryption means claudectl's plaintext TCP is fine
- Tailscale ACL tags let admins control which machines can form hive networks
---
## Combined UX: The "Just Works" Flow
With all four mechanisms, the ideal experience is:
### Same room, same WiFi (LAN discovery)
```
1. Both run: claudectl relay serve (or TUI with relay.enabled = true)
2. Both see each other in the discovery overlay
3. One presses "Pair", the other approves
4. Connected. Knowledge flows.
```
### Same team, same repo (project peers)
```
1. Lead runs: claudectl relay project-add && git commit && git push
2. Teammate clones, runs: claudectl relay project-connect
3. Pair request sent, approved, connected.
```
### Remote colleague (invite link)
```
1. You run: claudectl relay invite
2. Paste the link in Slack
3. They run: claudectl relay join <link>
4. Connected.
```
### Same Tailnet (auto-discovery)
```
1. Both enable: relay.tailscale = true
2. That's it. Auto-discovered, auto-paired, auto-connected.
```
---
## Implementation Priority
| Mechanism | Dependencies | Effort | Impact |
|-----------|-------------|--------|--------|
| Invite Links | None (string parsing) | Small | High — eliminates the most friction |
| LAN Discovery | `UdpSocket` (std::net) | Medium | High — zero-config for co-located teams |
| Project Peers | TOML parsing (already have) | Small | Medium — good for established teams |
| Tailscale | `tailscale` CLI | Medium | Medium — great for distributed teams |
**Recommended order:** Invite Links → LAN Discovery → Project Peers → Tailscale.
Invite links are the highest-leverage fix: one command, one copy-paste, done. LAN discovery is the most magical but requires more code. Project peers and Tailscale serve specific team topologies.
---
## Config Summary
```toml
[relay]
enabled = true
listen_port = 9847
# LAN discovery
lan_discovery = true
lan_announce_interval = 10
lan_broadcast_port = 9848
auto_approve_lan = false
# Tailscale integration
tailscale = false
tailscale_tag = "tag:claudectl"
tailscale_probe_interval = 60
# Invite links
invite_ttl_hours = 24
```
## CLI Summary
```bash
# Discovery
claudectl relay discover # scan LAN for nearby instances
claudectl relay project-peers # show project peer list
# Pairing (new)
claudectl relay invite [--qr] [--ttl 24h] # generate invite link
claudectl relay join <link> # accept invite link
claudectl relay pair-with <identity> # pair with discovered peer
# Project peers
claudectl relay project-init # create .claudectl/peers.toml
claudectl relay project-add # add yourself to peer list
claudectl relay project-connect # connect to all project peers
# Existing (unchanged)
claudectl relay serve
claudectl relay pair
claudectl relay accept <code> <peer-id>
claudectl relay connect <host:port>
claudectl relay peers
```