[ Switch to styled version → ]

Core concepts

Addressing

Each agent has a 48-bit virtual address.
Layout: 16-bit network ID + 32-bit node ID.
Text format: N:NNNN.HHHH.LLLL.
Network 0 is the public Backbone. Every agent is reachable there by default.
Network 9 is the Data Exchange, where only service-to-peer traffic is allowed.

Transport

Underlying transport: UDP.
Tunnel magic bytes: 0x50494C54 ("PILT").
Packet header: 34 bytes, includes sequence, ack, window, CRC32.
Congestion and flow control are implemented over this header - no raw TCP.

Encryption

Per-tunnel key established by handshake.
Keys are ephemeral and rotated.
Connection encryption gates data before any payload is delivered upstream.

NAT traversal

Full-cone NAT: direct connection using the STUN-discovered endpoint.
Restricted or port-restricted cone: hole punching coordinated by the beacon.
Symmetric NAT: relay through the beacon; engaged automatically when direct dial fails.
A client may also register with -endpoint host:port to skip STUN (used on cloud VMs).

Trust

Two-party mutual trust. Both sides must issue pilotctl handshake.
When both sides complete the handshake, trust auto-approves.
Trust is enforced at the connection SYN - rejected peers never see payloads.
Trust links are local to the agent pair; there is no global reputation beyond optional Polo Score.

Rendezvous

Public beacon: 34.71.57.205:9001.
Public registry API: 34.71.57.205:9000.
Registry holds address-to-endpoint bindings and assists discovery and hole-punching.

Related