The network stack for AI agents.
Addresses. Ports. Tunnels. Encryption. Trust. Zero dependencies.
Docs · Wire Spec · Whitepaper · IETF Draft · Agent Skills · Polo (Live Dashboard)
The internet was built for humans. AI agents have no address, no identity, no way to be reached. Pilot Protocol is an overlay network that gives agents what the internet gave devices: a permanent address, encrypted peer-to-peer channels, and a trust model -- all layered on top of standard UDP.
It is not an API. It is not a framework. It is infrastructure.
Today, agents talk through centralized APIs. Every connection requires a platform in the middle. There is no way for two agents to find each other, establish trust, or communicate directly.
graph LR
A1[Agent A] -->|HTTP API| P[Platform / Cloud]
A2[Agent B] -->|HTTP API| P
A3[Agent C] -->|HTTP API| P
style P fill:#f66,stroke:#333,color:#fff
style A1 fill:#4a9,stroke:#333,color:#fff
style A2 fill:#4a9,stroke:#333,color:#fff
style A3 fill:#4a9,stroke:#333,color:#fff
Pilot Protocol removes the middleman. Each agent gets a permanent address and talks directly to peers over encrypted tunnels:
graph LR
A1[Agent A<br/><small>0:0000.0000.0001</small>] <-->|Encrypted UDP Tunnel| A2[Agent B<br/><small>0:0000.0000.0002</small>]
A1 <-->|Encrypted UDP Tunnel| A3[Agent C<br/><small>0:0000.0000.0003</small>]
A2 <-->|Encrypted UDP Tunnel| A3
style A1 fill:#4a9,stroke:#333,color:#fff
style A2 fill:#4a9,stroke:#333,color:#fff
style A3 fill:#4a9,stroke:#333,color:#fff
|
Via CLI pilotctl info
pilotctl set-hostname my-agent
pilotctl find other-agent
pilotctl send other-agent 1000 --data "hello"
pilotctl recv 1000 --count 5 --timeout 30s |
Via Python SDK from pilotprotocol import Driver
with Driver() as d:
info = d.info()
d.set_hostname("my-agent")
peer = d.resolve_hostname("other-agent")
with d.dial("other-agent:1000") as conn:
conn.write(b"hello")
data = conn.read(4096) |
Every CLI command supports --json for structured output. The Python SDK wraps the Go driver via ctypes FFI. See examples/python_sdk/ for PydanticAI integration and more.
Example JSON output
$ pilotctl --json info
{"status":"ok","data":{"address":"0:0000.0000.0005","node_id":5,"hostname":"my-agent","peers":3,"connections":1,"uptime_secs":3600}}
$ pilotctl --json find other-agent
{"status":"ok","data":{"hostname":"other-agent","address":"0:0000.0000.0003"}}
$ pilotctl --json recv 1000 --count 1
{"status":"ok","data":{"messages":[{"seq":0,"port":1000,"data":"hello","bytes":5}]}}
$ pilotctl --json find nonexistent
{"status":"error","code":"not_found","message":"hostname not found: nonexistent","hint":"check the hostname and ensure mutual trust exists"}|
Addressing
Transport
|
Security
Operations
|
graph LR
subgraph Local Machine
Agent[Your Agent] -->|commands| CLI[pilotctl]
CLI -->|Unix socket| D[Daemon]
D --- E[Echo :7]
D --- DX[Data Exchange :1001]
D --- ES[Event Stream :1002]
D --- TS[Task Submit :1003]
end
D <====>|UDP Tunnel<br/>AES-256-GCM + NAT traversal| RD
subgraph Remote Machine
RD[Remote Daemon] -->|Unix socket| RC[pilotctl]
RC -->|commands| RA[Remote Agent]
RD --- RE[Echo :7]
RD --- RDX[Data Exchange :1001]
RD --- RES[Event Stream :1002]
RD --- RTS[Task Submit :1003]
end
D -.->|register + discover| RV
RD -.->|register + discover| RV
subgraph Rendezvous
RV[Registry :9000<br/>Beacon :9001]
end
Your agent talks to a local daemon over a Unix socket. The daemon handles tunnel encryption, NAT traversal, packet routing, congestion control, and built-in services. The daemon connects to a rendezvous server (registry + beacon) for node discovery and NAT hole-punching.
For connection lifecycle details, gateway bridging, and NAT traversal strategy, see the full documentation.
A public demo agent (agent-alpha) is running on the network with auto-accept enabled:
# 1. Install
curl -fsSL https://pilotprotocol.network/install.sh | sh
# 2. Start the daemon
pilotctl daemon start --hostname my-agent --email user@example.com
# 3. Request trust (auto-approved within seconds)
pilotctl handshake agent-alpha "hello"
# 4. Wait a few seconds, then verify trust
pilotctl trust
# 5. Start the gateway (maps the agent to a local IP)
sudo pilotctl gateway start --ports 80 0:0000.0000.0004
# 6. Open the website
curl http://10.4.0.1/You can also ping and benchmark:
pilotctl ping agent-alpha
pilotctl bench agent-alphacurl -fsSL https://pilotprotocol.network/install.sh | shSet a hostname and email during install:
curl -fsSL https://pilotprotocol.network/install.sh | PILOT_EMAIL=user@example.com PILOT_HOSTNAME=my-agent shWhat the installer does
- Detects your platform (linux/darwin, amd64/arm64)
- Downloads pre-built binaries from the latest release (falls back to building from source if Go is available)
- Installs
pilot-daemon,pilotctl, andpilot-gatewayto~/.pilot/bin - Adds
~/.pilot/binto your PATH - Writes
~/.pilot/config.jsonwith the public rendezvous server pre-configured - Sets up a system service (Linux: systemd, macOS: launchd)
Uninstall: curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstall
From source: git clone https://github.com/TeoSlayer/pilotprotocol.git && cd pilotprotocol && make build
pip install pilotprotocolSee the Python SDK documentation for the full API reference.
go test -parallel 4 -count=1 ./tests/683 tests pass, 26 skipped (IPv6, platform-specific). The -parallel 4 flag is required -- unlimited parallelism exhausts ports and causes dial timeouts.
| Document | Description |
|---|---|
| Docs Site | Guides, CLI reference, deployment, configuration, and integration patterns |
| Wire Specification | Packet format, addressing, flags, checksums |
| Whitepaper (PDF) | Full protocol design, transport, security, validation |
| IETF Problem Statement | Internet-Draft: why agents need network-layer infrastructure |
| IETF Protocol Specification | Internet-Draft: full protocol spec in IETF format |
| Agent Skills | Machine-readable skill definition for AI agent integration |
| Polo Dashboard | Live network stats, node directory, and tag search |
| Contributing | Guidelines for contributing to the project |
Pilot Protocol is licensed under the GNU Affero General Public License v3.0.
Vulture Labs
Built for agents, by humans.