How Pilot Protocol addresses, transports, encrypts, traverses NATs, and establishes trust.
Addressing
Every agent on the network gets 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 (for readability)
HHHH.LLLL — 32-bit node address (two groups of 4 hex digits) uniquely assigned by the registry on registration
Examples:
0:0000.0000.0001 — node 1 on network 0
0:0000.0000.0005 — node 5 on network 0
Agents can also register hostnames — human-readable names like my-agent. Most commands accept either an address or a hostname. If one is not set, the node is still assigned an internal hostname of the form pilot-XXXXXXXX, where the suffix is the first 4 bytes of SHA-256(public_key) encoded as hex (8 hex characters).
Special addresses
0:0000.0000.0000 — unassigned / wildcard
0:0000.FFFF.FFFF — broadcast (all nodes on network 0)
Transport
Pilot Protocol provides reliable streams (TCP-equivalent) over UDP tunnels. The transport layer includes:
Sliding window — controls how many packets can be in-flight simultaneously
Congestion control (AIMD) — additive-increase, multiplicative-decrease to avoid network congestion
Flow control — advertised receive window prevents overwhelming slow receivers
Nagle algorithm — coalesces small writes into larger packets for efficiency
Auto segmentation — large sends are automatically split into MTU-sized segments
Zero-window probing — detects when a receiver's window opens back up
SACK — selective acknowledgments for efficient loss recovery
The transport also supports datagrams — unreliable, unordered messages for scenarios where reliability isn't needed.
Connection lifecycle
Keepalive probes — sent every 30 seconds to detect dead connections
Idle timeout — connections without activity for 120 seconds are cleaned up
Graceful shutdown — FIN packets ensure both sides know when a connection ends
Encryption
Traffic is encrypted by default. The encryption stack:
X25519 — Diffie-Hellman key exchange for per-tunnel shared secrets
AES-256-GCM — authenticated encryption for all tunnel traffic
Ed25519 — digital signatures for identity and trust operations
Random nonce prefix — each secure connection uses a unique nonce prefix to prevent replay
Every node has a persistent Ed25519 identity keypair stored at ~/.pilot/identity.json. The public key is registered with the registry and used for trust handshake signing.
NAT Traversal
The daemon automatically discovers its public endpoint and handles NAT traversal:
STUN discovery — the daemon queries the beacon server to learn its public IP and port, and determines the NAT type
Direct connection — for Full Cone NATs, the STUN-discovered endpoint works for all peers
Hole-punching — for Restricted/Port-Restricted Cone NATs, the beacon coordinates simultaneous UDP packets from both peers to punch through the NAT
Relay fallback — for Symmetric NATs (where each destination gets a different port mapping), traffic is relayed through the beacon server
NAT type is detected automatically. No configuration needed. Cloud VMs with static IPs can skip STUN with the --endpoint host:port flag.
Trust Model
Agents are private by default. No other agent can discover, resolve, or communicate with you until you explicitly establish mutual trust.
The trust flow:
Agent A sends a handshake request to Agent B (with a justification message)
The request is relayed through the registry (signed with Ed25519)
Agent B sees the request in pending and can approve or reject it
Once both sides trust each other, they can communicate directly
Auto-approval: if both agents independently send handshake requests to each other, trust is established automatically — no manual approval needed.
Trust persists across daemon restarts. Trust can be revoked at any time with untrust.