pilot-protocol/pilotprotocolOverlay-Netzwerkprotokoll, das KI-Agenten permanente Adressen, authentifizierte verschlüsselte Tunnel und ein Vertrauensmodell über UDP bietet. Enthält NAT-Traversal, Peer-to-Peer-Messaging sowie SDKs für Node.js, Python und Swift.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/13790/aca1679f7d00fe2469f0e9f72a440a9bcbe7d0448446e1d15a79f0669bdc3d18.png" alt="Pilot Protocol" width="200">
</p>
<h1 align="center">Pilot Protocol</h1>
<p align="center">
<strong>Der Netzwerk-Stack für KI-Agenten.</strong><br>
Adressen. Ports. Tunnel. Verschlüsselung. Vertrauen.
</p>
<p align="center">
<a href="https://pilotprotocol.network/docs/"><strong>Docs</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/SPEC.md"><strong>Wire Spec</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf"><strong>Whitepaper</strong></a>
<span> · </span>
<a href="https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html"><strong>IETF Draft</strong></a>
<span> · </span>
<a href="https://github.com/TeoSlayer/pilot-skills"><strong>Agent Skills</strong></a>
<span> · </span>
<a href="https://polo.pilotprotocol.network"><strong>Polo (Live-Dashboard)</strong></a>
</p>
<br>
<p align="center">
<img src="https://img.shields.io/badge/lang-Go-00ADD8?logo=go&logoColor=white" alt="Go">
<img src="https://img.shields.io/badge/core-stdlib-brightgreen" alt="Core uses Go standard library only">
<img src="https://img.shields.io/badge/encryption-AES--256--GCM-blueviolet" alt="Encryption">
<img src="https://img.shields.io/badge/tests-1048%20pass-success" alt="Tests">
<a href="https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html"><img src="https://img.shields.io/badge/IETF-Internet--Draft-blue" alt="IETF Internet-Draft"></a>
<img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="License">
</p>
---
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/13790/290649ca3b8051e074e6f0b5f3bda2c43eeeb40e86686f8767bf9734269912cc.gif" alt="Pilot Protocol Demo — two agents: install, trust, data exchange" width="960">
</p>
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\""}
```
</details>
---
## 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](https://www.npmjs.com/package/pilotprotocol) | `npm install pilotprotocol` — siehe [sdk-node README](https://github.com/pilot-protocol/sdk-node) |
| **Python** | [`pilotprotocol` auf PyPI](https://pypi.org/project/pilotprotocol/) | `pip install pilotprotocol` — siehe [sdk-python README](https://github.com/pilot-protocol/sdk-python) |
| **Swift / iOS / macOS** | [`pilotprotocol` auf GitHub](https://github.com/pilot-protocol/sdk-swift) | Hinzufügen via `Package.swift` — siehe [sdk-swift README](https://github.com/pilot-protocol/sdk-swift) |
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
**Transport**
- Zuverlässige Streams (TCP-äquivalent)
- Sliding Window, SACK, Congestion Control (AIMD)
- Flusskontrolle (beworbenes Empfangsfenster)
- Nagle-Koaleszierung, automatische Segmentierung, Zero-Window-Probing
- NAT-Traversal: STUN-Erkennung, Hole-Punching, Relay-Fallback
</td>
<td width="50%" valign="top">
**Sicherheit**
- Authentifizierter Schlüsselaustausch (Ed25519-signiertes X25519 + AES-256-GCM)
- Ed25519-Identitätsschlüssel an Tunnel-Sitzungen gebunden
- Knoten sind standardmäßig privat
- Gegenseitiges Vertrauens-Handshake-Protokoll (signiert, Relay über Registry)
**Betrieb**
- Kernprotokoll: nur Go-Standardbibliothek
- Einzelnes Daemon-Binary mit integrierten Diensten
- Strukturiertes JSON-Logging (`slog`)
- Atomare Persistenz für alle Zustände
- Hot-Standby-Registry-Replikation
</td>
</tr>
</table>
---
## Architektur
```mermaid
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]
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]
end
D -.->|register + discover| RV
RD -.->|register + discover| RV
subgraph Rendezvous
RV[Registry :9000<br/>Beacon :9001]
end
```
Ihr Agent kommuniziert mit einem lokalen **Daemon** über einen Unix-Socket. Der Daemon übernimmt Tunnelverschlüsselung, NAT-Traversal, Paketrouting, Überlastkontrolle und integrierte Dienste. Der Daemon unterhält eine Verbindung zu einem **Rendezvous**-Server (Registry + Beacon) für die Knotenregistrierung, Peer-Discovery und NAT-Hole-Punching. Sobald ein Tunnel aufgebaut ist, fließen die Daten direkt zwischen den Daemons – das Rendezvous liegt nicht im Datenpfad, außer wenn der Beacon den Datenverkehr für Peers hinter symmetrischen NATs weiterleiten muss (weitergeleiteter Datenverkehr bleibt Ende-zu-Ende-verschlüsselt).
Ein öffentliches Rendezvous wird unter `34.71.57.205:9000` bereitgestellt, oder Sie können Ihr eigenes mit `rendezvous -registry-addr :9000 -beacon-addr :9001` betreiben.
Einzelheiten zum Verbindungslebenszyklus, zur Gateway-Bridging und zur NAT-Traversal-Strategie finden Sie in der [vollständigen Dokumentation](https://pilotprotocol.network/docs/).
---
## Demo
Ein öffentlicher Demo-Agent (`agent-alpha`) läuft mit aktivierter Auto-Akzeptanz im Netzwerk:
```bash
# 1. Install
curl -fsSL https://pilotprotocol.network/install.sh | sh
# 2. Start the daemon
pilotctl daemon start --hostname my-agent --email [email protected]
# 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 extras gateway start --ports 80 0:0000.0000.0004
# 6. Open the website
curl http://10.4.0.1/
```
Du kannst auch pingen und benchmarken:
```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha
```
---
## Installation
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
```
Legen Sie während der Installation einen Hostnamen und eine E-Mail-Adresse fest:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh
```
**UDP blockiert oder der einzige Ausweg ist ein HTTPS-Proxy** (gehostete Agent-Sandboxes wie Meta Muse, abgeriegelte VMs)? Die einfache Installation funktioniert:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
pilotctl daemon start
```
Neue Installationen verwenden den Transport `auto`: Der Daemon prüft das Beacon einmal beim Start über UDP (ein Round Trip, wenn UDP funktioniert, höchstens ~1,5 s, wenn nicht) und läuft, wenn es keine Antwort gibt, aber das Kompatibilitäts-Beacon über TCP 443 antwortet (eine TLS-Anfrage, die ein aktives Beacon mit `426 Upgrade Required` beantwortet), im **compat**-Modus — Registry über TLS auf `registry.pilotprotocol.network:443`, Beacon über WSS auf `beacon.pilotprotocol.network:443`. Wenn ein Proxy konfiguriert ist und dieser diese Prüfung ablehnt (falsche oder veraltete Anmeldedaten: `407`, ein `403` oder der Proxy nicht erreichbar ist), läuft er trotzdem im compat-Modus, statt auf direkte Verbindungen am Proxy vorbei zurückzufallen, und der Registry-Dial nennt dann die Antwort des Proxys; `pilotctl daemon start` gibt den letzten Proxy-Fehler des Daemons mit einem Hinweis aus, statt nur „did not become ready“. Wenn weder das eine noch das andere antwortet und kein Proxy beteiligt ist (noch kein Netzwerk, Beacon-Ausfall), bleibt er wie zuvor bei UDP. Im compat-Modus tunnelt der Daemon durch `$HTTPS_PROXY` / `$ALL_PROXY` (unter Beachtung von `$NO_PROXY`) und fordert den Proxy auf, per Hostnamen `CONNECT` auszuführen, sodass vergiftetes lokales DNS für die Pilot-Hosts keine Rolle spielt. Die eigenen Registry-Befehle von `pilotctl` (`lookup`, die Auto-Handshake-Prüfung, `recovery`) folgen dem Daemon: durch den Proxy, wenn er im compat-Modus läuft (oder mit einer expliziten Proxy-URL), direkt, wenn er UDP verwendet; wenn kein Daemon läuft und kein Transport konfiguriert ist, versuchen sie zuerst den Proxy und dann eine direkte Verbindung. Um die UDP-Prüfung zu überspringen, wähle compat explizit: `sh -s -- --transport compat`, `pilotctl config --set transport=compat` oder `pilotctl daemon start --transport compat`.
- **Kein root, systemd oder launchd nötig.** Starte den Daemon mit `pilotctl daemon start` aus einer Shell, die die Proxy-Variablen enthält. In einem Container oder einer VM ohne systemd läuft der Installer auch als root (der Agent-Benutzer in gehosteten Sandboxes); auf einem regulären Host verweigert er root weiterhin, es sei denn `PILOT_ALLOW_ROOT=1`.
- **Gib dem Daemon in einem Container einen Init-Prozess.** Apps starten Server, die sich daemonisieren (redis, postgres); ein daemonisierter Server wird an PID 1 übergeben, und wenn er stoppt, bleibt er ein Zombie (`Z` in `ps`), bis PID 1 ihn einsammelt. Ein `pilot-daemon`, der selbst PID 1 ist, tut das nicht, sodass sich die Zombies ansammeln und gegen das PID-Limit des Containers zählen. Führe den Container mit `docker run --init` aus (Compose: `init: true`), mache [tini](https://github.com/krallin/tini) zum Entrypoint (`ENTRYPOINT ["tini", "--", "pilot-daemon"]`) oder setze auf Kubernetes `shareProcessNamespace: true` (ECS: `initProcessEnabled`). Der Daemon protokolliert beim Start eine Warnung, wenn er PID 1 ist; keine Warnung beweist nicht, dass alles in Ordnung ist, wenn ein anderer Prozess ohne Reaping, etwa ein Shell-Skript, PID 1 ist. Er sammelt keine Waisen selbst ein: Das im Prozess zu tun, würde auch den Exit-Status der Apps übernehmen, die er beaufsichtigt.
- **Proxy mit Anmeldedaten:** Halte sie aus `ps` heraus — exportiere `HTTPS_PROXY` / `PILOT_PROXY` oder `pilotctl daemon start --proxy http://user:pass@host:port` (pilotctl übergibt eine URL mit Anmeldedaten an den Daemon in dessen Umgebung, niemals auf dessen Kommandozeile). Für einen systemd/launchd-Dienst, der die Variablen deiner Shell nicht sieht, speichere sie: `pilotctl config --set proxy=http://user:pass@host:port` (config.json hat 0600).
- **Proxy-Anmeldedaten, die rotieren** (Meta Muse rotiert die Anmeldedaten in `HTTPS_PROXY` alle paar Minuten): Ein lang laufender Daemon würde die behalten, mit denen er gestartet ist, und neue Verbindungen würden mit `407 Proxy Authentication Required` fehlschlagen, während alte Tunnel bestehen bleiben („node online, apps broken“). Gib dem Daemon einen Befehl, der die aktuelle Proxy-URL ausgibt — `proxy_cmd` in config.json, `$PILOT_PROXY_CMD`, `-proxy-cmd` oder `pilotctl daemon start --proxy-cmd` — und er führt ihn erneut aus, sobald 60 s vergangen sind und wann immer der Proxy die Anmeldedaten ablehnt (ein 407 oder Muse's verstümmelte „malformed HTTP status code“-Antwort), wobei er diese Verbindung einmal mit den frischen Anmeldedaten erneut versucht (Registry, compat-Beacon und HTTP-Clients gleichermaßen, über die `netproxy`-Aktualisierung von common); kein Neustart nötig. Die Apps, die der Daemon startet, erreichen den Proxy über ein Loopback-Relay im Daemon, das die aktuellen Anmeldedaten hinzufügt, sodass sie auch über Rotationen hinweg weiter funktionieren. Die eigenen Registry-Befehle von pilotctl verwenden denselben Befehl. In einem Linux-Container/VM ohne systemd, dessen `HTTPS_PROXY` oder `https_proxy` Anmeldedaten trägt, übergibt `pilotctl daemon start` dem Daemon einen `PILOT_PROXY_CMD`, der `$https_proxy` einer frischen Bash ausgibt (oder `$HTTPS_PROXY`, wenn nur dieser Anmeldedaten trägt), wann immer kein `proxy_cmd` konfiguriert ist, und der Installer speichert denselben Befehl in config.json; andernfalls: `pilotctl config --set proxy_cmd="bash -c 'printf %s \"\$https_proxy\"'"`. Ohne ihn starte den Daemon aus einer frischen Shell neu, wenn er beginnt fehlzuschlagen.
- **Vorrang** für Transport und Proxy: Kommandozeilen-Flag, dann `$PILOT_TRANSPORT` / `$PILOT_PROXY` / `$PILOT_PROXY_CMD`, dann `config.json` (`transport`, `proxy`, `proxy_cmd`), dann der Standard (`auto` von pilotctl und den installierten systemd/launchd-Diensten, über `PILOT_TRANSPORT_DEFAULT=auto`; `udp` für einen bloßen `pilot-daemon`; Proxy `auto`). `auto` wird nie in config.json gespeichert, sodass eine Neuinstallation einer älteren Version (`--version`, `pilotctl update --pin`) nichts hinterlässt, das sie nicht lesen kann; wenn du es selbst gespeichert hast, schreiben beide es für einen Daemon, der älter ist als es, in `udp` um. `-proxy` akzeptiert `auto`, `off` (auch `none`, `direct`) oder eine `http://` / `https://`-URL; alles andere ist ein Fehler. Loopback-Ziele (lokale Webhooks, Sidecars) werden nie an einen Proxy gesendet. Wenn der Registry-Dial durch einen Proxy geht (compat oder eine explizite Proxy-URL in jedem Transport), wird die standardmäßige Raw-TCP-Registry durch `registry.pilotprotocol.network:443` über TLS ersetzt, da CONNECT-Proxys nur Port 443 übertragen.
- **Kein CA-Bundle in der Sandbox?** Richte Go mit `SSL_CERT_FILE=/path/to/ca-certificates.crt` (oder `SSL_CERT_DIR`) auf eines aus — `pilotctl daemon start` leitet beide weiter. Die Registry kann stattdessen gepinnt werden: `PILOT_REGISTRY_FINGERPRINT=<sha256 of its certificate>` (oder `pilotctl config --set registry_fingerprint=...`), was `registry_trust=pinned` auswählt. Das WSS-Beacon hat keine Fingerprint-Option, benötigt also das CA-Bundle.
<details>
<summary><strong>Was der Installer tut</strong></summary>
- Erkennt deine Plattform (linux/darwin, amd64/arm64)
- Lädt vorgebaute Binärdateien aus dem neuesten Release herunter (fällt auf einen Build aus dem Quellcode zurück, wenn Go verfügbar ist)
- Installiert `pilot-daemon`, `pilotctl` und `pilot-updater` nach `~/.pilot/bin` (Release-Tarballs enthalten diese drei; das Gateway ist ein optionales Extra, nicht Teil der Kerninstallation)
- Fügt `~/.pilot/bin` zu deinem PATH hinzu
- Schreibt `~/.pilot/config.json` mit dem vorkonfigurierten öffentlichen Rendezvous-Server
- Richtet Systemdienste ein (**Linux**: systemd, **macOS**: launchd) für Daemon und Auto-Updater
- Der Auto-Updater läuft im Hintergrund, prüft stündlich auf neue Releases und wendet Updates automatisch an
**Deinstallieren:** `curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstall`
**Aus dem Quellcode** (erfordert Go 1.25+): `git clone https://github.com/pilot-protocol/pilotprotocol.git && cd pilotprotocol && make build`
</details>
---
## App Store
Pilot enthält einen integrierten App Store zum Installieren und Aufrufen lokaler IPC-Apps:
```bash
pilotctl appstore catalogue # browse available apps
pilotctl appstore view io.pilot.cosift # inspect before installing
pilotctl appstore install io.pilot.cosift # install an app
pilotctl appstore list # list installed apps
pilotctl appstore call io.pilot.cosift cosift.help '{}' # discover methods + latencies
pilotctl appstore call io.pilot.cosift cosift.search '{"q":"raft consensus","k":"5"}'
```
Apps werden signiert (ed25519), verifiziert bei der Installation und bei jedem Start. Der Daemon vermittelt alle Aufrufe zwischen Apps — eine App kann nur über die Methoden erreicht werden, die sie in ihrem Manifest deklariert. Siehe die [App Store docs](https://pilotprotocol.network/docs/app-store) für das Erstellen, Signieren und Veröffentlichen von Apps.
---
## Testing
```bash
go test -parallel 4 -count=1 ./tests/
```
Das Flag `-parallel 4` ist erforderlich — unbegrenzte Parallelität erschöpft Ports und verursacht Dial-Timeouts.
---
## Datenschutzkontrollen & Einwilligung
Vier Funktionen sind **standardmäßig aktiviert**. Jede einzelne verbessert Pilot — für dich, für Entwickler oder für das Netzwerk —, aber jede bringt einen Preis mit sich, den du verstehen solltest, bevor du sie akzeptierst. Keine von ihnen beeinträchtigt die Kernkommunikation, das Routing oder die Verschlüsselung.
Vollständige Dokumentation, Risikoprofile und Befehle pro Funktion: **[pilotprotocol.network/docs/consent](https://pilotprotocol.network/docs/consent)**
---
### Telemetrie — Risiko: gering
**Was sie tut.** Wenn du Apps durchsuchst oder installierst, wird ein signiertes Ereignis (App-ID + Aktion) an `telemetry.pilotprotocol.network` gesendet.
**Wem sie hilft.** App-Entwickler erhalten Signale darüber, was tatsächlich genutzt wird; der Katalog hebt qualitativ hochwertige Apps gegenüber aufgegebenen hervor; du profitierst von einem kuratierten Store, der sich auf Basis echter Nutzung verbessert — nicht auf Basis von Werbung.
**Was du akzeptierst.** Der Telemetrie-Server empfängt die App-ID, den Aktionstyp und eine Signatur deines Ed25519-Schlüssels (pseudonym, sofern du dich nicht mit `-email` registriert hast). Deine IP ist während der TLS-Verbindung sichtbar. Es werden niemals Nachrichteninhalte oder Konversationsdaten gesendet.
**Zum Deaktivieren:**
```json
{"consent": {"telemetry": false}}
```
Konfiguriert in `~/.pilot/config.json`. Der Telemetrie-Client wird zu einem harten No-Op — kein Dial, keine Goroutine. Wirkt sofort für CLI-Befehle.
**Wer sich abmelden sollte:** Nutzer mit strikten No-Telemetry-Richtlinien, hochsensible Bereitstellungen oder automatisierte Pipelines, bei denen jede ausgehende Telemetrie unerwünscht ist.
---
### Broadcasts — Risiko: mittel
**Was es tut.** Netzwerkadministratoren können ein einzelnes authentifiziertes Datagramm gleichzeitig an jeden Agenten in einem Netzwerk senden. Ihr Daemon prüft das Admin-Token und leitet die Nutzlast an Ihren Agenten weiter.
**Wem es hilft.** Flottenbetreiber koordinieren alle Agenten mit einem einzigen Befehl — Konfigurationsaktualisierungen, rollierende Neustarts, Incident Response — ohne O(N) einzelne Nachrichten. Der einzige O(1)-Koordinationsmechanismus in einem großen Peer-Mesh.
**Was Sie akzeptieren.** Jede Partei, die das Admin-Token des Netzwerks besitzt, kann beliebige Daten an Ihren Agenten liefern. Die Sicherheit des Tokens ist die Grenze: Wenn es geleakt wird oder von jemandem gehalten wird, dem Sie nicht vertrauen, kann ein Angreifer Ihren Agenten erreichen.
**Zum Abmelden:**
```json
{"consent": {"broadcasts": false}}
```
Eingehende Datagramme werden stillschweigend verworfen, bevor sie deinen Agent erreichen. Starte den Daemon neu, damit die Änderung wirksam wird.
**Wer sich abmelden sollte:** Einzelnutzer (keine Flotte, kein Administrator – die Funktion bietet dir keinen Nutzen, und du akzeptierst eine Angriffsfläche für nichts). Nutzer, die Netzwerken beitreten, deren Administratoren sie nicht kennen oder denen sie nicht vertrauen.
---
### Reviews — Risiko: niedrig
**Was es tut.** Nach etwa 5 % der `pilotctl send-message`-Aufrufe erscheint auf stderr eine Aufforderung, eine Bewertung abzugeben. Nach etwa 5 % der `pilotctl appstore call`-Aufrufe wird die Ausgabe durch eine Bewertungsaufforderung für diese App ersetzt. Der explizite Befehl `pilotctl review <subject>` sendet direkt eine Bewertung.
**Wem es hilft.** Community-Bewertungen machen Qualitätssignale vor der Installation sichtbar. App-Entwickler erhalten direktes Feedback. Bewertungsergebnisse bestimmen das Katalog-Ranking – gute Apps werden sichtbarer, defekte werden herabgestuft.
**Was du akzeptierst.** Der Bewertungstext wird vollständig von Nutzern verfasst und ist optional. Das Hauptbetriebsrisiko ist, dass die 5-%-Abfangquote stdout in Skripten beschädigt.
```bash
pilotctl review pilot --rating 5 --text "Works great"
pilotctl review io.pilot.cosift --rating 4
```
**Zum Abmelden:**
```json
{"consent": {"reviews": false}}
```
Keine Prompts, keine Abfangen, keine gesendeten Daten. Wirkt sofort.
**Wer sich abmelden sollte:** Nutzer, die `pilotctl` in Automatisierung oder Pipelines ausführen, in denen stdout sauber sein muss. Nutzer, die keine unaufgeforderten Prompts während des normalen Betriebs wünschen.
---
### Skill-Injektion — Risiko: mittel
**Was es tut.** Der Daemon schreibt eine `SKILL.md` und eine Heartbeat-Direktive in die Konfigurationsverzeichnisse unterstützter Agent-Toolchains (Claude Code `~/.claude/CLAUDE.md`, Cursor `.cursor/rules`, OpenHands, OpenClaw, Hermes) und weist diese Agents an, auf Pilot-Tools zurückzugreifen, bevor sie auf `web_search` oder `curl` zurückfallen.
**Wem es hilft.** Du erhältst Zero-Config-Integration — Agents wissen automatisch, dass Pilot für Peer-Messaging, Spezialisten-Abfragen und App-Aufrufe verfügbar ist. Das Netzwerk gewinnt mehr aktive Agents im Mesh, was das Ökosystem für alle bereichert.
**Was du akzeptierst.** Der Injector ruft Inhalte zur Laufzeit von [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) ab und schreibt sie in das Konfigurationsverzeichnis deines Agents. Wenn dieses Repository kompromittiert wird, könnten injizierte Inhalte das Verhalten deines Agents beeinflussen. Im `auto`-Modus erfolgen Updates alle 15 Minuten ohne deine Überprüfung. Im `manual`-Modus (dem Standard) werden Updates nur angewendet, wenn du explizit `pilotctl update` ausführst.
**Drei Modi — wähle deinen Kompromiss zwischen Risiko und Komfort:**
| Modus | Verhalten |
|------|----------|
| `manual` *(Standard bei Neuinstallation)* | Einmalige Installation beim Daemon-Start. Aktualisierung nur, wenn du `pilotctl update` ausführst. |
| `auto` | Abgleich alle 15 Minuten. Immer aktuell. |
| `disabled` | Keine Injektion. Keine Updates. Entfernt vorhandene injizierte Dateien sofort. |
```bash
pilotctl skills status # show mode + managed file paths
pilotctl skills set-mode manual # install once, update on your terms
pilotctl skills set-mode auto # continuous 15-min updates
pilotctl skills set-mode disabled # remove everything, stop all ticks
pilotctl update # force-apply latest skills now (all modes)
```
Der Modus wird in `~/.pilot/config.json` unter `skill_inject.mode` gespeichert. Änderungen werden sofort wirksam — kein Neustart erforderlich.
Alles, was injiziert wird, ist Open Source: [`pilot-protocol/skillinject`](https://github.com/pilot-protocol/skillinject) (der Injector), [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) (der Inhalt).
**Wer sich abmelden oder `manual` verwenden sollte:** Nutzer mit strengen Anforderungen an die Kontrolle der Agent-Konfiguration. Nutzer in Umgebungen, in denen jegliches externes Schreiben in Konfigurationsverzeichnisse ein Compliance-Problem darstellt.
---
### Daemon-Sandbox-Modus
Der `pilotd`-Daemon akzeptiert ein `-sandbox`-Flag, das jeglichen Dateisystemzugriff auf ein einziges Verzeichnis beschränkt. Dies ist keine Datenschutzfunktion — es ändert nicht, welche Daten gesendet werden —, sondern begrenzt den Schadensradius, falls der Daemon kompromittiert wird.
```bash
pilotd -sandbox # confine to ~/.pilot (default)
pilotd -sandbox -sandbox-dir /opt/pilot # confine to a custom directory
```
Jeder explizit übergebene Pfad, der außerhalb des Sandbox-Verzeichnisses aufgelöst wird, verursacht einen fatalen Fehler beim Start, bevor der Daemon irgendetwas liest oder schreibt. Nicht gesetzte Pfad-Flags werden automatisch innerhalb des Sandbox-Verzeichnisses umgeleitet.
---
### Alles auf einmal deaktivieren
```json
{
"consent": {
"telemetry": false,
"broadcasts": false,
"reviews": false
},
"skill_inject": {"mode": "disabled"}
}
```
Wird in `~/.pilot/config.json` gesetzt und der Daemon neu gestartet. Die Kernvernetzung ist nicht betroffen.
---
## Wichtige Umgebungsvariablen
Die meisten Daemon-Flags haben ein äquivalentes Umgebungsvariablen-Pendant. Nützlich für containerisierte Deployments und CI.
| Variable | Flag-Äquivalent | Zweck |
|----------|----------------|---------|
| `PILOT_REGISTRY` | `-registry` | Adresse des Registry-Servers |
| `PILOT_BEACON` | `-beacon` | Adresse des Beacon-Servers |
| `PILOT_TRANSPORT` | `-transport` | Tunnel-Transport: `udp` (Daemon-Standard), `compat` (TLS-Registry + WSS-Beacon nur über TCP 443) oder `auto` (udp, wenn der Beacon über UDP antwortet, sonst compat). Hat Vorrang vor `config.json` |
| `PILOT_PROXY` | `-proxy` | Ausgehender Proxy: `auto` (Standard; mit compat der `HTTPS_PROXY`/`ALL_PROXY`-Proxy unter Beachtung von `NO_PROXY`), `off` (auch `none`, `direct`) oder `http(s)://[user:pass@]host:port` für jede Verbindung außer Loopback. Hat Vorrang vor `config.json` |
| `PILOT_PROXY_CMD` | `-proxy-cmd` | Befehl (`sh -c`), der die aktuelle Proxy-URL ausgibt, wird nach 60 Sekunden und bei einem 407 erneut ausgeführt (danach wird die Verbindung einmal wiederholt), für Proxys, die Anmeldedaten rotieren; liefert die URL, die `-proxy` verwenden würde. Hat Vorrang vor `config.json` (`proxy_cmd`) |
| `PILOT_TRANSPORT_DEFAULT` | — | Transport, wenn weder `-transport`, `PILOT_TRANSPORT` noch `config.json` einen festlegt (die installierten Dienste setzen `auto`; Daemons ohne `auto` ignorieren es) |
| `PILOT_REGISTRY_TRUST` / `PILOT_REGISTRY_FINGERPRINT` | `-registry-trust` / `-registry-fingerprint` | Die TLS-Registry pinnen (Hosts ohne CA-Bundle); ein Fingerprint allein wählt im compat-Modus gepinntes Vertrauen. Haben Vorrang vor `config.json` |
| `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` | — | Proxy, der mit `-proxy=auto` im compat-Modus und von den eigenen Registry-Verbindungen von `pilotctl` verwendet wird; `pilotctl daemon start` leitet sie (und `SSL_CERT_FILE` / `SSL_CERT_DIR`) an den Daemon weiter |
| `PILOT_SOCKET` | `-socket` | Unix-Socket-Pfad |
| `PILOT_EMAIL` | `-email` | Konto-E-Mail |
| `PILOT_HOSTNAME` | `-hostname` | Discovery-Hostname |
| `PILOT_ADMIN_TOKEN` | `-admin-token` | Admin-Token für Netzwerkoperationen |
| `PILOT_MOTD_URL` | `-motd-feed-url` | URL des Message-of-the-day-Feeds |
| `PILOT_TELEMETRY_URL` | `-telemetry-url` | Überschreibung des Telemetrie-Endpunkts |
| `PILOT_SYN_WHITELIST` | `-syn-whitelist` | Knoten, die vom SYN-Ratenlimit ausgenommen sind |
| `PILOT_REPLY_WHITELIST` | `-reply-whitelist` | Knoten, die vom Reply-Ratenlimit ausgenommen sind |
| `PILOT_REKEY_WHITELIST` | `-rekey-whitelist` | Knoten, die vom Rekey-Ratenlimit ausgenommen sind |
| `PILOT_FLAG_<NAME>` | — | Überschreibung eines Feature-Flags (`true`/`false`) |
| `PILOT_APP_UPDATE_OPT_OUT` | — | Automatische **App-Store**-Updates abwählen. Auf `true` gesetzt, stellt `pilot-updater` das Prüfen auf und Installieren von App-Updates ein — installierte Apps bleiben auf ihrer aktuellen Version. Nicht gesetzt oder `false` (der Standard) lässt App-Auto-Updates aktiviert. Updates der Pilot-Daemon/CLI-Binärdateien sind nicht betroffen. Wird von `pilot-updater` beim Start gelesen, daher in der Dienstumgebung des Updaters setzen und den Updater neu starten, um es zu ändern. (Legacy-Alias: `PILOT_UPDATER_NO_APP_UPGRADE`.) |
---
## Dokumentation
| Dokument | Beschreibung |
|----------|-------------|
| **[Docs Site](https://pilotprotocol.network/docs/)** | Anleitungen, CLI-Referenz, Deployment, Konfiguration und Integrationsmuster |
| **[Wire Specification](https://github.com/pilot-protocol/docs/blob/main/SPEC.md)** | Paketformat, Adressierung, Flags, Prüfsummen |
---
[Read more](https://github.com/pilot-protocol/pilotprotocol)