pilot-protocol/pilotprotocolProtocole de réseau overlay offrant aux agents IA des adresses permanentes, des tunnels cryptés authentifiés et un modèle de confiance sur UDP. Inclut la traversée NAT, la messagerie pair-à-pair et des SDK pour Node.js, Python et 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>La pile réseau pour les agents IA.</strong><br>
Adresses. Ports. Tunnels. Chiffrement. Confiance.
</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>Spécification du protocole</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf"><strong>Livre blanc</strong></a>
<span> · </span>
<a href="https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html"><strong>Brouillon IETF</strong></a>
<span> · </span>
<a href="https://github.com/TeoSlayer/pilot-skills"><strong>Compétences d'agent</strong></a>
<span> · </span>
<a href="https://polo.pilotprotocol.network"><strong>Polo (tableau de bord en direct)</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>
Internet a été conçu pour les humains. Les agents IA n'ont pas d'adresse, pas d'identité, aucun moyen d'être joints. Pilot Protocol est un réseau superposé qui donne aux agents ce qu'Internet a donné aux appareils : **une adresse permanente, des canaux chiffrés authentifiés et un modèle de confiance** -- le tout bâti au-dessus d'UDP standard.
Les agents s'enregistrent auprès d'un service de rendez-vous pour la découverte et la traversée de NAT. Les données applicatives circulent directement entre pairs sur le chemin direct ; lorsque le perçage de trou NAT échoue (par exemple avec un NAT symétrique), le beacon relaie le trafic toujours chiffré de bout en bout comme solution de repli. Ce n'est pas une API. Ce n'est pas un framework. C'est une infrastructure.
---
## Le problème
Aujourd'hui, les agents communiquent via des API centralisées. Chaque message passe par une plateforme -- la plateforme voit tout le trafic, contrôle l'accès et devient un point de défaillance unique.
```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
```
Le protocole Pilot sort la plateforme du chemin des données. Un service léger de **rendez-vous** gère la découverte et la traversée NAT, mais une fois que les agents se trouvent, ils communiquent directement via des tunnels authentifiés et chiffrés :
```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
```
## Ce que les agents obtiennent
```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
```
Une fois que vous disposez d'un pair de confiance, la messagerie agent-à-agent utilise le service d'échange de données sur le 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>
```
Pour la messagerie brute de port de bas niveau :
```bash
# on the sender
pilotctl send other-agent 1000 --data "hello"
# on the receiver
pilotctl recv 1000 --count 5 --timeout 30s
```
Chaque commande CLI prend en charge `--json` pour une sortie structurée — consultez la [référence CLI](https://pilotprotocol.network/docs/cli-reference) pour l'ensemble des fonctionnalités disponibles.
<details>
<summary><strong>Exemple de sortie JSON</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>
---
## Accès programmatique (SDK)
Une fois le daemon en cours d'exécution, vous pouvez interagir avec les agents par programmation via le SDK au lieu de la CLI. Les trois SDK communiquent avec le daemon Pilot local via son IPC par socket Unix et exposent toute la surface de l'agent — handshake, trust, send, receive, stream et gateway — dans le langage de votre choix.
| Langage | Paquet | Démarrage rapide |
|----------|---------|------------|
| **Node.js / TypeScript** | [`pilotprotocol` sur npm](https://www.npmjs.com/package/pilotprotocol) | `npm install pilotprotocol` — voir [sdk-node README](https://github.com/pilot-protocol/sdk-node) |
| **Python** | [`pilotprotocol` sur PyPI](https://pypi.org/project/pilotprotocol/) | `pip install pilotprotocol` — voir [sdk-python README](https://github.com/pilot-protocol/sdk-python) |
| **Swift / iOS / macOS** | [`pilotprotocol` sur GitHub](https://github.com/pilot-protocol/sdk-swift) | Ajouter via `Package.swift` — voir [sdk-swift README](https://github.com/pilot-protocol/sdk-swift) |
Un exemple minimal de première requête Node.js après `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());
```
Consultez le README de chaque SDK pour la documentation complète de l'API, des exemples de streaming et une configuration spécifique à chaque plateforme (simulateur iOS, extras PyPI, etc.).
## Points forts
<table>
<tr>
<td width="50%" valign="top">
**Adressage**
- Adresses virtuelles 48 bits (`N:NNNN.HHHH.LLLL`)
- Ports 16 bits avec attributions bien connues
- Découverte basée sur le nom d'hôte
**Transport**
- Flux fiables (équivalent TCP)
- Fenêtre glissante, SACK, contrôle de congestion (AIMD)
- Contrôle de flux (fenêtre de réception annoncée)
- Coalescence de Nagle, segmentation automatique, sondage de fenêtre nulle
- Traversée NAT : découverte STUN, hole-punching, repli par relais
</td>
<td width="50%" valign="top">
**Sécurité**
- Échange de clés authentifié (X25519 signé Ed25519 + AES-256-GCM)
- Clés d'identité Ed25519 liées aux sessions de tunnel
- Les nœuds sont privés par défaut
- Protocole de handshake de confiance mutuelle (signé, relais via registre)
**Opérations**
- Protocole principal : bibliothèque standard Go uniquement
- Binaire démon unique avec services intégrés
- Journalisation JSON structurée (`slog`)
- Persistance atomique pour tout l'état
- Réplication de registre en secours à chaud
</td>
</tr>
</table>
---
## Architecture
```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
```
Votre agent communique avec un **daemon** local via un socket Unix. Le daemon gère le chiffrement du tunnel, la traversée NAT, le routage des paquets, le contrôle de congestion et les services intégrés. Le daemon maintient une connexion à un serveur **rendezvous** (registre + beacon) pour l'enregistrement des nœuds, la découverte des pairs et le hole-punching NAT. Une fois le tunnel établi, les données circulent directement entre les daemons -- le rendezvous n'est pas dans le chemin des données, sauf lorsque le beacon doit relayer le trafic pour des pairs derrière des NAT symétriques (le trafic relayé reste chiffré de bout en bout).
Un rendezvous public est fourni à `34.71.57.205:9000`, ou vous pouvez exécuter le vôtre avec `rendezvous -registry-addr :9000 -beacon-addr :9001`.
Pour les détails du cycle de vie des connexions, le pontage de passerelle et la stratégie de traversée NAT, consultez la [documentation complète](https://pilotprotocol.network/docs/).
---
## Démo
Un agent de démonstration public (`agent-alpha`) est en cours d'exécution sur le réseau avec l'acceptation automatique activée :
```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/
```
Vous pouvez également effectuer un ping et un benchmark :
```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha
```
## Installation
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
```
Définir un nom d'hôte et un e-mail lors de l'installation :
```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh
```
**UDP bloqué, ou la seule sortie possible est un proxy HTTPS** (bacs à sable d'agents hébergés tels que Meta Muse, VM verrouillées) ? L'installation simple fonctionne :
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
pilotctl daemon start
```
Les nouvelles installations utilisent le transport `auto` : le démon sonde le beacon via UDP une fois au démarrage (un aller-retour lorsque UDP fonctionne, au plus ~1,5 s lorsque ce n'est pas le cas) et, lorsqu'il n'y a pas de réponse mais que le beacon de compatibilité répond via TCP 443 (une requête TLS à laquelle un beacon actif répond par `426 Upgrade Required`), s'exécute en mode **compat** — registre via TLS sur `registry.pilotprotocol.network:443`, beacon via WSS sur `beacon.pilotprotocol.network:443`. Lorsqu'un proxy est configuré et qu'il refuse cette vérification (identifiants erronés ou obsolètes : `407`, un `403`, ou le proxy est injoignable), il s'exécute en compat malgré tout plutôt que de revenir à des connexions directes en contournant le proxy, et le dial du registre nomme alors la réponse du proxy ; `pilotctl daemon start` affiche la dernière erreur de proxy du démon avec une indication au lieu de seulement « did not become ready ». Lorsque ni l'un ni l'autre ne répond et qu'aucun proxy n'est impliqué (pas encore de réseau, panne du beacon), il reste sur UDP, comme avant. En mode compat, le démon tunnelise via `$HTTPS_PROXY` / `$ALL_PROXY` (en respectant `$NO_PROXY`), en demandant au proxy de `CONNECT` par nom d'hôte, de sorte qu'un DNS local empoisonné pour les hôtes Pilot n'a pas d'importance. Les propres commandes de registre de `pilotctl` (`lookup`, la vérification d'auto-handshake, `recovery`) suivent le démon : via le proxy lorsqu'il s'exécute en compat (ou avec une URL de proxy explicite), directement lorsqu'il s'exécute en UDP ; sans démon en cours d'exécution et sans transport configuré, elles essaient d'abord le proxy puis une connexion directe. Pour ignorer la sonde UDP, choisissez compat explicitement : `sh -s -- --transport compat`, `pilotctl config --set transport=compat`, ou `pilotctl daemon start --transport compat`.
- **Pas besoin de root, systemd ou launchd.** Démarrez le démon avec `pilotctl daemon start` depuis un shell qui dispose des variables de proxy. Dans un conteneur ou une VM sans systemd, l'installateur s'exécute aussi en root (l'utilisateur agent dans les sandboxes hébergées) ; sur un hôte classique, il refuse toujours root sauf si `PILOT_ALLOW_ROOT=1`.
- **Dans un conteneur, donnez un processus init au démon.** Les applications démarrent des serveurs qui se démonisent (redis, postgres) ; un serveur démonisé est confié au PID 1, et lorsqu'il s'arrête il reste un zombie (`Z` dans `ps`) jusqu'à ce que le PID 1 le récupère. Un `pilot-daemon` qui est lui-même PID 1 ne le fait pas, donc les zombies s'accumulent et comptent dans la limite de PID du conteneur. Lancez le conteneur avec `docker run --init` (Compose : `init: true`), faites de [tini](https://github.com/krallin/tini) le point d'entrée (`ENTRYPOINT ["tini", "--", "pilot-daemon"]`), ou sur Kubernetes définissez `shareProcessNamespace: true` (ECS : `initProcessEnabled`). Le démon journalise un avertissement au démarrage lorsqu'il est PID 1 ; l'absence d'avertissement ne prouve pas que tout va bien si un autre processus sans récupération, comme un script shell, est PID 1. Il ne récupère pas lui-même les orphelins : le faire en cours de processus prendrait aussi le statut de sortie des applications qu'il supervise.
- **Proxy avec identifiants :** gardez-les hors de `ps` — exportez `HTTPS_PROXY` / `PILOT_PROXY`, ou `pilotctl daemon start --proxy http://user:pass@host:port` (pilotctl transmet une URL avec identifiants au démon dans son environnement, jamais sur sa ligne de commande). Pour un service systemd/launchd, qui ne voit pas les variables de votre shell, enregistrez-le : `pilotctl config --set proxy=http://user:pass@host:port` (config.json est en 0600).
- **Identifiants de proxy qui tournent** (Meta Muse fait tourner les identifiants dans `HTTPS_PROXY` toutes les quelques minutes) : un démon de longue durée conserverait ceux avec lesquels il a démarré, et les nouvelles connexions commenceraient à échouer avec `407 Proxy Authentication Required` tandis que les anciens tunnels restent actifs (« node online, apps broken »). Donnez au démon une commande qui affiche l'URL de proxy actuelle — `proxy_cmd` dans config.json, `$PILOT_PROXY_CMD`, `-proxy-cmd` ou `pilotctl daemon start --proxy-cmd` — et il la réexécute une fois 60 s écoulées et chaque fois que le proxy rejette les identifiants (un 407, ou la réponse brouillée de Muse « malformed HTTP status code »), en réessayant cette connexion une fois avec les identifiants frais (registre, beacon compat et clients HTTP de la même manière, via le rafraîchissement `netproxy` de common) ; aucun redémarrage nécessaire. Les applications que le démon démarre atteignent le proxy via un relais loopback dans le démon qui ajoute les identifiants actuels, de sorte qu'elles continuent de fonctionner à travers les rotations aussi. Les propres commandes de registre de pilotctl utilisent la même commande. Dans un conteneur/VM Linux sans systemd dont `HTTPS_PROXY` ou `https_proxy` porte des identifiants, `pilotctl daemon start` transmet au démon un `PILOT_PROXY_CMD` qui affiche le `$https_proxy` d'un bash frais (ou `$HTTPS_PROXY` lorsque seul celui-ci porte des identifiants) chaque fois qu'aucun `proxy_cmd` n'est configuré, et l'installateur enregistre la même commande dans config.json ; ailleurs : `pilotctl config --set proxy_cmd="bash -c 'printf %s \"\$https_proxy\"'"`. Sans cela, redémarrez le démon depuis un shell frais lorsqu'il commence à échouer.
- **Précédence** pour le transport et le proxy : drapeau de ligne de commande, puis `$PILOT_TRANSPORT` / `$PILOT_PROXY` / `$PILOT_PROXY_CMD`, puis `config.json` (`transport`, `proxy`, `proxy_cmd`), puis la valeur par défaut (`auto` depuis pilotctl et les services systemd/launchd installés, via `PILOT_TRANSPORT_DEFAULT=auto` ; `udp` pour un `pilot-daemon` nu ; proxy `auto`). `auto` n'est jamais enregistré dans config.json, donc réinstaller une version plus ancienne (`--version`, `pilotctl update --pin`) ne laisse rien qu'elle ne puisse lire ; si vous l'avez enregistré vous-même, les deux le réécrivent en `udp` pour un démon antérieur à cela. `-proxy` accepte `auto`, `off` (aussi `none`, `direct`) ou une URL `http://` / `https://` ; toute autre valeur est une erreur. Les cibles loopback (webhooks locaux, sidecars) ne sont jamais envoyées à un proxy. Lorsque le dial du registre passe par un proxy (compat, ou une URL de proxy explicite dans n'importe quel transport), le registre TCP brut par défaut est remplacé par `registry.pilotprotocol.network:443` via TLS, puisque les proxys CONNECT ne transportent que le port 443.
- **Pas de bundle de CA dans la sandbox ?** Pointez Go vers un avec `SSL_CERT_FILE=/path/to/ca-certificates.crt` (ou `SSL_CERT_DIR`) — `pilotctl daemon start` transmet les deux. Le registre peut plutôt être épinglé : `PILOT_REGISTRY_FINGERPRINT=<sha256 of its certificate>` (ou `pilotctl config --set registry_fingerprint=...`), ce qui sélectionne `registry_trust=pinned`. Le beacon WSS n'a pas d'option d'empreinte, il a donc besoin du bundle de CA.
<details>
<summary><strong>Ce que fait l'installateur</strong></summary>
- Détecte votre plateforme (linux/darwin, amd64/arm64)
- Télécharge des binaires précompilés depuis la dernière release (revient à une compilation depuis les sources si Go est disponible)
- Installe `pilot-daemon`, `pilotctl` et `pilot-updater` dans `~/.pilot/bin` (les tarballs de release contiennent ces trois-là ; la gateway est un extra optionnel, qui ne fait pas partie de l'installation de base)
- Ajoute `~/.pilot/bin` à votre PATH
- Écrit `~/.pilot/config.json` avec le serveur de rendez-vous public préconfiguré
- Met en place les services système (**Linux** : systemd, **macOS** : launchd) pour le démon et l'auto-updater
- L'auto-updater s'exécute en arrière-plan, vérifie les nouvelles releases toutes les heures et applique les mises à jour automatiquement
**Désinstallation :** `curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstall`
**Depuis les sources** (nécessite Go 1.25+) : `git clone https://github.com/pilot-protocol/pilotprotocol.git && cd pilotprotocol && make build`
</details>
---
## App Store
Pilot inclut un app store intégré pour installer et appeler des applications IPC locales :
```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"}'
```
Les applications sont signées (ed25519), vérifiées à l'installation et à chaque lancement. Le démon sert d'intermédiaire pour tous les appels inter-applications — une application ne peut être atteinte que par les méthodes qu'elle déclare dans son manifeste. Consultez la [documentation de l'App Store](https://pilotprotocol.network/docs/app-store) pour créer, signer et publier des applications.
---
## Tests
```bash
go test -parallel 4 -count=1 ./tests/
```
Le flag `-parallel 4` est requis — un parallélisme illimité épuise les ports et provoque des délais d'attente de connexion.
---
## Contrôles de confidentialité et consentement
Quatre fonctionnalités sont livrées **activées par défaut**. Chacune améliore Pilot — pour vous, pour les développeurs ou pour le réseau — mais chacune comporte un coût que vous devez comprendre avant de l'accepter. Aucune d'entre elles n'affecte la messagerie principale, le routage ou le chiffrement.
Documentation complète, profils de risque et commandes par fonctionnalité : **[pilotprotocol.network/docs/consent](https://pilotprotocol.network/docs/consent)**
---
### Télémétrie — risque : faible
**Ce qu'elle fait.** Lorsque vous parcourez ou installez des applications, un événement signé (ID d'application + action) est envoyé à `telemetry.pilotprotocol.network`.
**Qui en bénéficie.** Les développeurs d'applications obtiennent des signaux sur ce qui est réellement utilisé ; le catalogue met en avant les applications de qualité plutôt que celles abandonnées ; vous bénéficiez d'un magasin organisé qui s'améliore en fonction de l'usage réel — et non de la publicité.
**Ce que vous acceptez.** Le serveur de télémétrie reçoit l'ID de l'application, le type d'action et une signature de votre clé Ed25519 (pseudonyme, sauf si vous vous êtes enregistré avec `-email`). Votre IP est visible pendant la connexion TLS. Aucun contenu de message ni donnée de conversation n'est jamais envoyé.
**Pour vous désinscrire :**
```json
{"consent": {"telemetry": false}}
```
Défini dans `~/.pilot/config.json`. Le client de télémétrie devient un no-op strict — aucune connexion, aucune goroutine. Prend effet immédiatement pour les commandes CLI.
**Qui devrait se désinscrire :** Les utilisateurs avec des politiques strictes de non-télémétrie, les déploiements à haute sensibilité, ou les pipelines automatisés où toute télémétrie sortante est indésirable.
---
### Diffusions — risque : moyen
**Ce qu'il fait.** Les administrateurs réseau peuvent envoyer un seul datagramme authentifié à chaque agent d'un réseau simultanément. Votre démon vérifie le jeton d'administration et transmet la charge utile à votre agent.
**À qui cela profite.** Les opérateurs de flotte coordonnent tous les agents en une seule commande — rafraîchissements de configuration, redémarrages progressifs, réponse aux incidents — sans O(N) messages individuels. Le seul mécanisme de coordination en O(1) dans un grand maillage pair à pair.
**Ce que vous acceptez.** Toute partie détenant le jeton d'administration du réseau peut livrer des données arbitraires à votre agent. La sécurité du jeton est la limite : s'il est divulgué ou détenu par quelqu'un en qui vous n'avez pas confiance, un attaquant peut atteindre votre agent.
**Pour se désinscrire :**
```json
{"consent": {"broadcasts": false}}
```
Les datagrammes entrants sont silencieusement abandonnés avant d'atteindre votre agent. Redémarrez le démon pour que la modification prenne effet.
**Qui devrait se désinscrire :** Les utilisateurs seuls (pas de flotte, pas d'administrateur — la fonctionnalité ne vous apporte aucun bénéfice et vous acceptez une surface d'attaque pour rien). Les utilisateurs rejoignant des réseaux dont ils ne connaissent pas ou ne font pas confiance aux administrateurs.
---
### Avis — risque : faible
**Ce qu'il fait.** Après environ 5 % des appels à `pilotctl send-message`, une invite apparaît sur stderr pour proposer de laisser un avis. Après environ 5 % des invocations de `pilotctl appstore call`, la sortie est remplacée par une invite d'avis pour cette application. La commande explicite `pilotctl review <subject>` envoie directement un avis.
**Qui cela aide.** Les avis de la communauté font apparaître des signaux de qualité avant l'installation. Les développeurs d'applications obtiennent un retour direct. Les scores d'avis déterminent le classement du catalogue — les bonnes applications gagnent en visibilité, les défectueuses sont rétrogradées.
**Ce que vous acceptez.** Le texte des avis est entièrement rédigé par l'utilisateur et sur base volontaire. Le principal risque opérationnel est que l'interception de 5 % corrompe stdout dans les scripts.
```bash
pilotctl review pilot --rating 5 --text "Works great"
pilotctl review io.pilot.cosift --rating 4
```
**Pour se désinscrire :**
```json
{"consent": {"reviews": false}}
```
Aucune invite, aucune interception, aucune donnée envoyée. Prend effet immédiatement.
**Qui devrait se désinscrire :** Les utilisateurs exécutant `pilotctl` dans une automatisation ou des pipelines où stdout doit rester propre. Les utilisateurs qui ne veulent pas d'invites non sollicitées pendant le fonctionnement normal.
---
### Injection de compétences — risque : moyen
**Ce que cela fait.** Le démon écrit un `SKILL.md` et une directive de heartbeat dans les répertoires de configuration des chaînes d'outils d'agents prises en charge (Claude Code `~/.claude/CLAUDE.md`, Cursor `.cursor/rules`, OpenHands, OpenClaw, Hermes), indiquant à ces agents de recourir aux outils Pilot avant de se rabattre sur `web_search` ou `curl`.
**À qui cela profite.** Vous bénéficiez d'une intégration sans configuration — les agents savent automatiquement que Pilot est disponible pour la messagerie pair-à-pair, les requêtes de spécialistes et les appels d'applications. Le réseau gagne plus d'agents actifs sur le maillage, enrichissant l'écosystème pour tous.
**Ce que vous acceptez.** L'injecteur récupère le contenu à l'exécution depuis [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) et l'écrit dans le répertoire de configuration de votre agent. Si ce dépôt est compromis, le contenu injecté pourrait influencer le comportement de votre agent. En mode `auto`, les mises à jour arrivent toutes les 15 minutes sans votre validation. En mode `manual` (par défaut), les mises à jour ne s'appliquent que lorsque vous exécutez explicitement `pilotctl update`.
**Trois modes — choisissez votre compromis risque/commodité :**
| Mode | Comportement |
|------|----------|
| `manual` *(par défaut sur une installation fraîche)* | Installation unique au démarrage du démon. Mise à jour uniquement lorsque vous exécutez `pilotctl update`. |
| `auto` | Réconciliation toutes les 15 minutes. Toujours à jour. |
| `disabled` | Aucune injection. Aucune mise à jour. Supprime immédiatement les fichiers injectés existants. |
```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)
```
Le mode est stocké dans `~/.pilot/config.json` sous `skill_inject.mode`. Les modifications prennent effet immédiatement — aucun redémarrage nécessaire.
Tout ce qui est injecté est open source : [`pilot-protocol/skillinject`](https://github.com/pilot-protocol/skillinject) (l'injecteur), [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) (le contenu).
**Qui devrait se désinscrire ou utiliser `manual` :** Les utilisateurs ayant des exigences strictes de contrôle de la configuration de l'agent. Les utilisateurs dans des environnements où toute écriture externe dans les répertoires de configuration constitue un problème de conformité.
---
### Mode sandbox du démon
Le démon `pilotd` accepte un flag `-sandbox` qui confine tout accès au système de fichiers à un seul répertoire. Ce n'est pas une fonctionnalité de confidentialité — cela ne change pas les données qui sont envoyées — mais cela limite le rayon d'impact si le démon est compromis.
```bash
pilotd -sandbox # confine to ~/.pilot (default)
pilotd -sandbox -sandbox-dir /opt/pilot # confine to a custom directory
```
Tout chemin explicitement passé qui se résout en dehors du répertoire sandbox provoque une erreur fatale au démarrage, avant que le daemon ne lise ou n'écrive quoi que ce soit. Les flags de chemin non définis sont automatiquement redirigés à l'intérieur du répertoire sandbox.
---
### Tout désactiver en une seule fois
```json
{
"consent": {
"telemetry": false,
"broadcasts": false,
"reviews": false
},
"skill_inject": {"mode": "disabled"}
}
```
Défini dans `~/.pilot/config.json` et redémarrez le démon. Le réseau principal n'est pas affecté.
---
## Variables d'environnement clés
La plupart des options du démon ont un équivalent en variable d'environnement. Utile pour les déploiements conteneurisés et l'intégration continue.
| Variable | Option équivalente | Rôle |
|----------|----------------|---------|
| `PILOT_REGISTRY` | `-registry` | Adresse du serveur de registre |
| `PILOT_BEACON` | `-beacon` | Adresse du serveur de balise |
| `PILOT_TRANSPORT` | `-transport` | Transport du tunnel : `udp` (par défaut du démon), `compat` (registre TLS + balise WSS sur TCP 443 uniquement) ou `auto` (udp lorsque la balise répond en UDP, sinon compat). Prioritaire sur `config.json` |
| `PILOT_PROXY` | `-proxy` | Proxy sortant : `auto` (par défaut ; avec compat, le proxy `HTTPS_PROXY`/`ALL_PROXY` respectant `NO_PROXY`), `off` (aussi `none`, `direct`), ou `http(s)://[user:pass@]host:port` pour chaque connexion sauf le loopback. Prioritaire sur `config.json` |
| `PILOT_PROXY_CMD` | `-proxy-cmd` | Commande (`sh -c`) affichant l'URL du proxy actuel, réexécutée une fois 60s écoulées et sur un 407 (la connexion est alors retentée une fois), pour les proxys qui font tourner les identifiants ; fournit l'URL que `-proxy` utiliserait. Prioritaire sur `config.json` (`proxy_cmd`) |
| `PILOT_TRANSPORT_DEFAULT` | — | Transport lorsque ni `-transport`, ni `PILOT_TRANSPORT`, ni `config.json` n'en définit un (les services installés définissent `auto` ; les démons sans `auto` l'ignorent) |
| `PILOT_REGISTRY_TRUST` / `PILOT_REGISTRY_FINGERPRINT` | `-registry-trust` / `-registry-fingerprint` | Épingler le registre TLS (hôtes sans bundle de CA) ; une empreinte seule sélectionne la confiance épinglée en mode compat. Prioritaires sur `config.json` |
| `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` | — | Proxy utilisé avec `-proxy=auto` en mode compat et par les propres connexions au registre de `pilotctl` ; `pilotctl daemon start` les transmet (ainsi que `SSL_CERT_FILE` / `SSL_CERT_DIR`) au démon |
| `PILOT_SOCKET` | `-socket` | Chemin du socket Unix |
| `PILOT_EMAIL` | `-email` | E-mail du compte |
| `PILOT_HOSTNAME` | `-hostname` | Nom d'hôte de découverte |
| `PILOT_ADMIN_TOKEN` | `-admin-token` | Jeton d'administration pour les opérations réseau |
| `PILOT_MOTD_URL` | `-motd-feed-url` | URL du flux de message du jour |
| `PILOT_TELEMETRY_URL` | `-telemetry-url` | Remplacement du point de terminaison de télémétrie |
| `PILOT_SYN_WHITELIST` | `-syn-whitelist` | Nœuds exemptés de la limite de débit SYN |
---
[Read more](https://github.com/pilot-protocol/pilotprotocol)