Pilot Protocol

Der Netzwerk-Stack für KI-Agenten.
Adressen. Ports. Tunnel. Verschlüsselung. Vertrauen.

Docs  ·  Wire Spec  ·  Whitepaper  ·  IETF Draft  ·  Agent Skills  ·  Polo (Live-Dashboard)

---

Das Internet wurde für Menschen gebaut. KI-Agenten haben keine Adresse, keine Identität, keine Möglichkeit, erreicht zu werden. Pilot Protocol ist ein Overlay-Netzwerk, das Agenten gibt, was das Internet Geräten gab: eine permanente Adresse, authentifizierte verschlüsselte Kanäle und ein Vertrauensmodell -- alles aufbauend auf Standard-UDP.

Agenten registrieren sich bei einem Rendezvous-Dienst für Discovery und NAT-Traversal. Anwendungsdaten fließen direkt zwischen Peers auf dem direkten Pfad; wenn NAT-Hole-Punching fehlschlägt (z. B. bei symmetrischem NAT), leitet der Beacon den weiterhin Ende-zu-Ende-verschlüsselten Datenverkehr als Fallback weiter. Es ist keine API. Es ist kein Framework. Es ist Infrastruktur.

---

Das Problem

Heutzutage kommunizieren Agenten über zentralisierte APIs. Jede Nachricht läuft über eine Plattform -- die Plattform sieht den gesamten Datenverkehr, kontrolliert den Zugriff und wird zum Single Point of Failure.```mermaid 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

Das Pilot-Protokoll nimmt die Plattform aus dem Datenpfad. Ein leichtgewichtiger **Rendezvous**-Dienst übernimmt die Erkennung und NAT-Traversierung, aber sobald die Agenten einander gefunden haben, kommunizieren sie direkt über authentifizierte, verschlüsselte Tunnel:```mermaid
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
    A1 -.->|discovery| RV[Rendezvous]
    A2 -.->|discovery| RV
    A3 -.->|discovery| RV
    style A1 fill:#4a9,stroke:#333,color:#fff
    style A2 fill:#4a9,stroke:#333,color:#fff
    style A3 fill:#4a9,stroke:#333,color:#fff
    style RV fill:#888,stroke:#333,color:#fff

Was Agenten erhalten```bash

pilotctl info # show your address, hostname, peer count pilotctl set-hostname my-agent # claim a name other agents can resolve pilotctl find agent-alpha # resolve a public demo peer pilotctl ping agent-alpha # round-trip over the encrypted tunnel pilotctl bench agent-alpha # 1 MB echo benchmark

Sobald Sie einen vertrauenswürdigen Peer haben, verwendet die Agent-zu-Agent-Kommunikation den Datenaustauschdienst auf Port 1001:```bash
# Send a structured message (waits for reply by default)
pilotctl send-message other-agent --data "hello"

# Read messages delivered to your inbox
pilotctl inbox

# Read a specific message
pilotctl inbox read <id>

Für Low-Level-Rohport-Messaging:```bash

on the sender

pilotctl send other-agent 1000 --data "hello"

on the receiver

pilotctl recv 1000 --count 5 --timeout 30s

Jeder CLI-Befehl unterstützt `--json` für strukturierte Ausgabe — siehe die [CLI-Referenz](https://pilotprotocol.network/docs/cli-reference) für den vollständigen Funktionsumfang.

<details>
<summary><strong>Beispiel für JSON-Ausgabe</strong></summary>```json
$ 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":"cannot find \"nonexistent\" — hostname not found or no mutual trust","hint":"establish trust first: pilotctl handshake nonexistent \"reason\""}

---

Programmatischer Zugriff (SDKs)

Sobald der Daemon läuft, kannst du programmatisch über die SDKs mit Agents interagieren, anstatt über die CLI. Alle drei SDKs kommunizieren mit dem lokalen Pilot-Daemon über dessen Unix-Socket-IPC und stellen die vollständige Agent-Oberfläche bereit — Handshake, Trust, Senden, Empfangen, Streamen und Gateway — in der Sprache deiner Wahl.

Sprache	Paket	Schnellstart
Node.js / TypeScript	pilotprotocol auf npm	npm install pilotprotocol — siehe sdk-node README
Python	pilotprotocol auf PyPI	pip install pilotprotocol — siehe sdk-python README
Swift / iOS / macOS	pilotprotocol auf GitHub	Hinzufügen via Package.swift — siehe sdk-swift README

Ein minimales Node.js-Beispiel für die erste Abfrage nach daemon start:```js import { createPilot, createAgent } from 'pilotprotocol';

const pilot = await createPilot(); const conn = await pilot.handshake('agent-alpha', 'hello'); await conn.trust();

// Send a message await conn.send(3000, Buffer.from('ping'));

// Receive on any port const msgs = await conn.recv(3000, { count: 1, timeout: 10 }); console.log('Received:', msgs[0].data.toString());

Siehe die README jeder SDK für vollständige API-Dokumentation, Streaming-Beispiele und plattformspezifische Einrichtung (iOS-Simulator, PyPI-Extras usw.).

## Highlights

<table>
<tr>
<td width="50%" valign="top">

**Adressierung**
- 48-Bit-virtuelle Adressen (`N:NNNN.HHHH.LLLL`)
- 16-Bit-Ports mit wohlbekannten Zuordnungen
- Hostnamen-basierte Erkennung