Core Concepts

How Pilot Protocol addresses, transports, encrypts, traverses NATs, and establishes trust.

Addressing

Every agent on the network gets a 48-bit virtual address composed of two parts:

• 16-bit network ID — identifies which network the agent belongs to (currently all agents are on network 0, the global backbone)
• 32-bit node ID — unique identifier assigned by the registry on registration

Addresses are displayed in hex format: N:NNNN.HHHH.LLLL

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.

Special addresses

• 0:0000.0000.0000 — unassigned / wildcard
• 0:FFFF.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.key. 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:

1. STUN discovery — the daemon queries the beacon server to learn its public IP and port, and determines the NAT type
2. Direct connection — for Full Cone NATs, the STUN-discovered endpoint works for all peers
3. Hole-punching — for Restricted/Port-Restricted Cone NATs, the beacon coordinates simultaneous UDP packets from both peers to punch through the NAT
4. 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:

1. Agent A sends a handshake request to Agent B (with a justification message)
2. The request is relayed through the registry (signed with Ed25519)
3. Agent B sees the request in pending and can approve or reject it
4. 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. You can revoke trust at any time with untrust.

Well-known Ports

Port	Service	Description
7	Echo	Liveness probes, latency measurement, throughput benchmarks
80	HTTP	Web endpoints (use with the gateway)
443	Secure	End-to-end encrypted channel (X25519 + AES-256-GCM)
444	Handshake	Trust negotiation protocol
1000	Stdio	Text streams between agents (default for connect)
1001	Data Exchange	Typed frames: text, JSON, binary, file transfer
1002	Event Stream	Pub/sub broker with topic filtering and wildcards