Relay Discovery and Pairing UX

Status: design spec. Invite codes, word phrases, QR, cctl:// links and UDP LAN discovery have shipped; hive discover extends the same announcer to named hives. See Relay & Hive Mind for how pairing works today — this document is the reasoning behind the four mechanisms, not a status page.

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:

Mechanism	Radius	Trust Model	Effort
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

# 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):

{"type": "announce", "identity": "laptop-a3f2", "port": 9847, "version": "0.36.0", "paired_count": 1}

Pair request (TCP, after user initiates):

{"type": "pair_request", "from": "desktop-b7c1", "psk_proposal": "<hex-encoded-canonical-psk>"}

Pair response (TCP):

{"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

[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`

# 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

# 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 .gitignored 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

# 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

# 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.

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

# 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

Check if tailscale CLI is available
Run tailscale status --json to get the peer list
For each peer, probe port 9847 to see if claudectl relay is running
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

[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

[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

# 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

Relay Discovery and Pairing UX

The Problem

Design Principle

Mechanism 1: LAN Broadcast Discovery

How it works

CLI flow

TUI flow

Protocol

Security considerations

Config

Implementation notes

Mechanism 2: Project Peers (Git-based)

How it works

File format: .claudectl/peers.toml

CLI flow

How pairing works

Security

Mechanism 3: Invite Links

How it works

Link format

CLI flow

Advantages over manual pairing

TTL enforcement

QR code

Mechanism 4: Tailscale Auto-Discovery

How it works

Detection

Trust model

Config

Why this works well

Combined UX: The "Just Works" Flow

Same room, same WiFi (LAN discovery)

Same team, same repo (project peers)

Remote colleague (invite link)

Same Tailnet (auto-discovery)

Implementation Priority

Config Summary

CLI Summary

File format: `.claudectl/peers.toml`