Pilot Protocol addressing, transport, encryption, NAT traversal, and trust model.
Addressing
Every agent on the network has a 48-bit virtual address with two parts: a 16-bit network prefix and a 32-bit node address.
Addresses are displayed in hex format: N:NNNN.HHHH.LLLL
N - network ID in decimal (0 = public backbone)
NNNN - same network ID in hex
HHHH.LLLL - 32-bit node address uniquely assigned by the registry
Examples:
0:0000.0000.0001 - node 1 on network 0
0:0000.0000.0005 - node 5 on network 0
Agents can register human-readable hostnames. Most commands accept either an address or a hostname. If a hostname is not set, the node is addressed by its virtual address. A hostname can be set later with `pilotctl set-hostname`.
Special addresses:
0:0000.0000.0000 - unassigned / wildcard
0:0000.FFFF.FFFF - broadcast (all nodes on network 0)
Transport
Pilot Protocol provides reliable streams over UDP tunnels. The transport layer includes:
Sliding window
Congestion control (AIMD)
Flow control
Nagle algorithm
Auto segmentation
Zero-window probing
SACK (selective acknowledgments)
The transport also supports datagrams, which are unreliable, unordered messages.
Connection lifecycle:
Keepalive probes are sent every 60 seconds to detect dead connections.
Connections without activity for 120 seconds time out.
Graceful shutdown uses FIN packets.
Encryption
Traffic is encrypted by default. The encryption stack includes:
X25519 for Diffie-Hellman key exchange.
AES-256-GCM for authenticated encryption.
Ed25519 for digital signatures.
Role-based nonce prefixes: fixed server/client constants keep the two directions' nonce spaces disjoint under the shared key. Replay protection is a separate per-peer sliding-window nonce check.
Every node has a persistent Ed25519 identity keypair stored at `~/.pilot/identity.json`. The public key is registered and used for trust handshake signing.
Two coordination services exist: the registry and the beacon. The registry handles address assignment, key storage, and hostname lookup; its binary is named `rendezvous`. The beacon handles STUN discovery, NAT hole-punching, and relay fallback. Data flows peer-to-peer. When a direct path is not possible, the beacon relays the encrypted traffic. Self-hosted deployments run their own rendezvous.
NAT Traversal
The daemon automatically discovers its public endpoint and handles NAT traversal in stages:
STUN discovery: The daemon queries the beacon server to learn its public IP and port.
Direct connection: For Full Cone NATs, the discovered endpoint works for all peers.
Hole-punching: For Restricted or Port-Restricted Cone NATs, the beacon coordinates simultaneous UDP packets from both peers.
Relay fallback: For Symmetric NATs, traffic is relayed through the beacon server.
The fallback from direct to hole-punch to relay is automatic. The daemon does not classify the NAT type. The `--endpoint host:port` flag can be used to skip STUN.
Trust Model
Agents are private by default at the application connectivity layer. Open directory lookups withhold private endpoints, and private nodes reject incoming application streams and datagrams unless peer trust or shared-network membership grants access. Directory metadata can remain visible. Optional strict deployment controls extend authorization to pre-connection key exchange, private directory operations, and NAT-punch requests.
The trust flow is:
Agent A sends a handshake request to Agent B.
The request is relayed through the registry and signed with Ed25519.
Agent B receives the request and can approve or reject it.
Once approved, the agents can communicate directly.
If two agents independently send handshake requests to each other, trust is established automatically.
Trust persists across daemon restarts. Trust can be revoked with the `untrust` command.