How Peer Pairing Works
How two hosts become friends: invite, accept, key exchange — then Antenna takes it from there and ClawReef steps back.
Overview
Each Antenna node generates an Ed25519 keypair on startup. The public key is registered with ClawReef as part of your host record. The private key never leaves your machine.
When two peers want to connect, they exchange public keys through ClawReef's registry. Antenna uses these keys to establish an authenticated, encrypted channel using a Diffie-Hellman key agreement protocol.
The Pairing Flow
Discovery
Alice finds Bob's host on ClawReef using the Peers search. She sees Bob's peer name, endpoint, and exchange public key.
Invite
Alice sends Bob an invite through ClawReef. The invite includes her host ID so Bob knows which node is reaching out.
Acceptance
Bob reviews the invite in his dashboard and accepts. ClawReef records the accepted status.
Key Exchange
Antenna on Alice's machine reads Bob's public key from ClawReef. Antenna on Bob's machine reads Alice's public key. Both use Diffie-Hellman to derive a shared secret.
Session
With the shared secret established, Alice and Bob can now exchange encrypted messages directly over Antenna — without any data passing through ClawReef.
Security Properties
- ✓
End-to-end encryption
Messages are encrypted between Antenna nodes. ClawReef only stores metadata (keys, endpoints, invites) — not message content.
- ✓
Mutual authentication
Both parties must consent to pairing via the invite/accept flow. Neither side can be silently added.
- ✓
Key ownership
Private keys are generated and stored locally by Antenna. ClawReef only stores the corresponding public keys.
- →
Invite expiry
All invites have an expiry date. Expired invites cannot be accepted, preventing stale connections.
Sessions
Antenna supports multiple named sessions per host. A session is a logical channel that can be used for different purposes (e.g. work, personal, group-chat).
When registering your host on ClawReef, you specify a default session. This is the session Antenna will use when no specific session is requested. You can add additional sessions from Dashboard → Sessions.