pilot-protocol/pilotprotocolProtocollo di rete overlay che fornisce agli agenti AI indirizzi permanenti, tunnel crittografati autenticati e un modello di fiducia su UDP. Include traversal NAT, messaggistica peer-to-peer e SDK per Node.js, Python e 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>Lo stack di rete per gli agenti AI.</strong><br>
Indirizzi. Porte. Tunnel. Crittografia. Fiducia.
</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>
Internet è stato costruito per gli esseri umani. Gli agenti AI non hanno un indirizzo, un'identità, né un modo per essere raggiunti. Pilot Protocol è una rete overlay che dà agli agenti ciò che Internet ha dato ai dispositivi: **un indirizzo permanente, canali autenticati e cifrati, e un modello di fiducia** -- il tutto stratificato sopra UDP standard.
Gli agenti si registrano presso un servizio di rendezvous per la scoperta e il NAT traversal. I dati applicativi fluiscono direttamente tra i peer sul percorso diretto; quando l'hole-punching NAT fallisce (ad es. NAT simmetrico), il beacon inoltra il traffico, comunque cifrato end-to-end, come fallback. Non è un'API. Non è un framework. È infrastruttura.
---
## Il problema
Oggi gli agenti comunicano attraverso API centralizzate. Ogni messaggio passa attraverso una piattaforma -- la piattaforma vede tutto il traffico, controlla l'accesso e diventa un singolo punto di guasto.
```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
```
Il Pilot Protocol rimuove la piattaforma dal percorso dei dati. Un leggero servizio di **rendezvous** gestisce la scoperta e il NAT traversal, ma una volta che gli agenti si trovano tra loro, comunicano direttamente tramite tunnel autenticati e cifrati:
```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
```
---
## Cosa ottengono gli agenti
```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
```
Una volta che hai un peer attendibile, la messaggistica da agente ad agente utilizza il servizio di scambio dati sulla porta 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>
```
Per la messaggistica raw di porte di livello inferiore:
```bash
# on the sender
pilotctl send other-agent 1000 --data "hello"
# on the receiver
pilotctl recv 1000 --count 5 --timeout 30s
```
Ogni comando CLI supporta `--json` per l'output strutturato — consulta il [riferimento CLI](https://pilotprotocol.network/docs/cli-reference) per l'intera superficie di utilizzo.
<details>
<summary><strong>Esempio di output 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>
---
## Accesso programmatico (SDK)
Una volta che il daemon è in esecuzione, puoi interagire con gli agenti in modo programmatico tramite l'SDK invece che dalla CLI. Tutti e tre gli SDK comunicano con il daemon locale Pilot attraverso il suo socket Unix IPC ed espongono l'intera superficie degli agenti — handshake, trust, send, receive, stream e gateway — nella lingua che preferisci.
| Linguaggio | Pacchetto | Avvio rapido |
|----------|---------|------------|
| **Node.js / TypeScript** | [`pilotprotocol` su npm](https://www.npmjs.com/package/pilotprotocol) | `npm install pilotprotocol` — vedi [sdk-node README](https://github.com/pilot-protocol/sdk-node) |
| **Python** | [`pilotprotocol` su PyPI](https://pypi.org/project/pilotprotocol/) | `pip install pilotprotocol` — vedi [sdk-python README](https://github.com/pilot-protocol/sdk-python) |
| **Swift / iOS / macOS** | [`pilotprotocol` su GitHub](https://github.com/pilot-protocol/sdk-swift) | Aggiungi tramite `Package.swift` — vedi [sdk-swift README](https://github.com/pilot-protocol/sdk-swift) |
Un esempio minimale di prima query in Node.js dopo `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());
```
Consulta il README di ciascun SDK per la documentazione completa delle API, esempi di streaming e configurazione specifica per piattaforma (simulatore iOS, extra PyPI, ecc.).
## In evidenza
<table>
<tr>
<td width="50%" valign="top">
**Indirizzamento**
- Indirizzi virtuali a 48 bit (`N:NNNN.HHHH.LLLL`)
- Porte a 16 bit con assegnazioni well-known
- Discovery basata su hostname
**Trasporto**
- Stream affidabili (equivalenti a TCP)
- Sliding window, SACK, controllo di congestione (AIMD)
- Controllo di flusso (finestra di ricezione annunciata)
- Coalescing di Nagle, segmentazione automatica, probing a finestra zero
- NAT traversal: discovery STUN, hole-punching, fallback su relay
</td>
<td width="50%" valign="top">
**Sicurezza**
- Scambio di chiavi autenticato (X25519 firmato con Ed25519 + AES-256-GCM)
- Chiavi di identità Ed25519 legate alle sessioni tunnel
- I nodi sono privati per impostazione predefinita
- Protocollo di handshake a fiducia reciproca (firmato, relay tramite registry)
**Operazioni**
- Protocollo core: solo libreria standard Go
- Binario demone singolo con servizi integrati
- Logging JSON strutturato (`slog`)
- Persistenza atomica per tutto lo stato
- Replicazione del registry in hot-standby
</td>
</tr>
</table>
---
## Architettura
```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
```
Il tuo agent comunica con un **daemon** locale tramite un socket Unix. Il daemon gestisce la crittografia del tunnel, la traversata NAT, l'instradamento dei pacchetti, il controllo della congestione e i servizi integrati. Il daemon mantiene una connessione a un server **rendezvous** (registry + beacon) per la registrazione dei nodi, la scoperta dei peer e il NAT hole-punching. Una volta stabilito un tunnel, i dati fluiscono direttamente tra i daemon -- il rendezvous non è nel percorso dei dati, tranne quando il beacon deve inoltrare il traffico per i peer dietro NAT simmetrici (il traffico inoltrato rimane crittografato end-to-end).
Un rendezvous pubblico è fornito all'indirizzo `34.71.57.205:9000`, oppure puoi eseguirne uno tuo con `rendezvous -registry-addr :9000 -beacon-addr :9001`.
Per i dettagli sul ciclo di vita delle connessioni, il bridging dei gateway e la strategia di traversata NAT, consulta la [documentazione completa](https://pilotprotocol.network/docs/).
---
## Demo
Un agent demo pubblico (`agent-alpha`) è in esecuzione sulla rete con l'accettazione automatica abilitata:
```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/
```
Puoi anche eseguire ping e benchmark:
```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha
```
---
## Installazione
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
```
Imposta un hostname e un'email durante l'installazione:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh
```
**UDP bloccato, o l'unica via d'uscita è un proxy HTTPS** (sandbox di agenti ospitati come Meta Muse, VM bloccate)? L'installazione semplice funziona:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
pilotctl daemon start
```
Le nuove installazioni usano il transport `auto`: il daemon sonda il beacon via UDP una volta all'avvio (un round trip quando UDP funziona, al massimo ~1,5s quando non funziona) e, quando non c'è risposta ma il beacon compat risponde su TCP 443 (una richiesta TLS a cui un beacon attivo risponde con `426 Upgrade Required`), viene eseguito in modalità **compat** — registry su TLS su `registry.pilotprotocol.network:443`, beacon su WSS su `beacon.pilotprotocol.network:443`. Quando è configurato un proxy e questo rifiuta quel controllo (credenziali errate o scadute: `407`, un `403`, o il proxy non è raggiungibile), viene eseguito in compat comunque invece di ricadere su connessioni dirette aggirando il proxy, e il dial del registry riporta poi la risposta del proxy; `pilotctl daemon start` stampa l'ultimo errore del proxy del daemon con un suggerimento invece del solo "did not become ready". Quando nessuno dei due risponde e non è coinvolto alcun proxy (nessuna rete ancora, beacon non disponibile) rimane su UDP, come prima. In modalità compat il daemon effettua il tunneling attraverso `$HTTPS_PROXY` / `$ALL_PROXY` (rispettando `$NO_PROXY`), chiedendo al proxy di `CONNECT` tramite nome host, così il DNS locale avvelenato per gli host Pilot non ha importanza. I comandi registry di `pilotctl` (`lookup`, il controllo auto-handshake, `recovery`) seguono il daemon: attraverso il proxy quando questo viene eseguito in compat (o con un URL proxy esplicito), direttamente quando viene eseguito in UDP; senza daemon in esecuzione e senza transport configurato provano prima il proxy e poi una connessione diretta. Per saltare la sonda UDP, scegli esplicitamente compat: `sh -s -- --transport compat`, `pilotctl config --set transport=compat`, oppure `pilotctl daemon start --transport compat`.
- **Nessun root, systemd o launchd necessario.** Avvia il daemon con `pilotctl daemon start` da una shell che ha le variabili del proxy. In un container o VM senza systemd l'installer viene eseguito anche come root (l'utente agent nelle sandbox ospitate); su un host normale rifiuta comunque root a meno che `PILOT_ALLOW_ROOT=1`.
- **In un container, assegna al daemon un processo init.** Le app avviano server che si daemonizzano (redis, postgres); un server daemonizzato viene assegnato al PID 1, e quando si ferma rimane uno zombie (`Z` in `ps`) finché il PID 1 non lo raccoglie. Un `pilot-daemon` che è esso stesso PID 1 non lo fa, quindi gli zombie si accumulano e contano contro il limite di PID del container. Esegui il container con `docker run --init` (Compose: `init: true`), rendi [tini](https://github.com/krallin/tini) l'entrypoint (`ENTRYPOINT ["tini", "--", "pilot-daemon"]`), oppure su Kubernetes imposta `shareProcessNamespace: true` (ECS: `initProcessEnabled`). Il daemon registra un avviso all'avvio quando è PID 1; l'assenza di avviso non prova che tutto vada bene se qualche altro processo senza reaping, come uno script shell, è PID 1. Non raccoglie gli orfani da solo: farlo in-process prenderebbe anche lo stato di uscita delle app che supervisiona.
- **Proxy con credenziali:** tienile fuori da `ps` — esporta `HTTPS_PROXY` / `PILOT_PROXY`, oppure `pilotctl daemon start --proxy http://user:pass@host:port` (pilotctl passa un URL con credenziali al daemon nel suo ambiente, mai sulla sua riga di comando). Per un servizio systemd/launchd, che non vede le variabili della tua shell, salvalo: `pilotctl config --set proxy=http://user:pass@host:port` (config.json è 0600).
- **Credenziali proxy che ruotano** (Meta Muse ruota le credenziali in `HTTPS_PROXY` ogni pochi minuti): un daemon di lunga durata manterrebbe quelle con cui è stato avviato, e le nuove connessioni inizierebbero a fallire con `407 Proxy Authentication Required` mentre i vecchi tunnel restano attivi ("node online, apps broken"). Assegna al daemon un comando che stampa l'URL proxy corrente — `proxy_cmd` in config.json, `$PILOT_PROXY_CMD`, `-proxy-cmd` o `pilotctl daemon start --proxy-cmd` — e lo rieseguirà una volta trascorsi 60s e ogni volta che il proxy rifiuta le credenziali (un 407, o la risposta confusa di Muse "malformed HTTP status code"), ritentando quella connessione una volta con le credenziali fresche (registry, beacon compat e client HTTP allo stesso modo, tramite il refresh `netproxy` di common); nessun riavvio necessario. Le app che il daemon avvia raggiungono il proxy attraverso un relay loopback nel daemon che aggiunge le credenziali correnti, così continuano a funzionare anche attraverso le rotazioni. I comandi registry di pilotctl usano lo stesso comando. In un container/VM Linux senza systemd il cui `HTTPS_PROXY` o `https_proxy` porta credenziali, `pilotctl daemon start` passa al daemon un `PILOT_PROXY_CMD` che stampa il `$https_proxy` di una bash fresca (o `$HTTPS_PROXY` quando solo quello porta credenziali) ogni volta che nessun `proxy_cmd` è configurato, e l'installer salva lo stesso comando in config.json; altrove: `pilotctl config --set proxy_cmd="bash -c 'printf %s \"\$https_proxy\"'"`. Senza di esso, riavvia il daemon da una shell fresca quando inizia a fallire.
- **Precedenza** per transport e proxy: flag da riga di comando, poi `$PILOT_TRANSPORT` / `$PILOT_PROXY` / `$PILOT_PROXY_CMD`, poi `config.json` (`transport`, `proxy`, `proxy_cmd`), poi il default (`auto` da pilotctl e dai servizi systemd/launchd installati, tramite `PILOT_TRANSPORT_DEFAULT=auto`; `udp` per un `pilot-daemon` nudo; proxy `auto`). `auto` non viene mai salvato in config.json, quindi reinstallare una release più vecchia (`--version`, `pilotctl update --pin`) non lascia nulla che non possa leggere; se l'hai salvato tu stesso, entrambi lo riscrivono in `udp` per un daemon precedente ad esso. `-proxy` accetta `auto`, `off` (anche `none`, `direct`) o un URL `http://` / `https://`; qualsiasi altra cosa è un errore. I target loopback (webhook locali, sidecar) non vengono mai inviati a un proxy. Quando il dial del registry passa attraverso un proxy (compat, o un URL proxy esplicito in qualsiasi transport), il registry raw-TCP predefinito viene sostituito da `registry.pilotprotocol.network:443` su TLS, poiché i proxy CONNECT trasportano solo la porta 443.
- **Nessun CA bundle nella sandbox?** Punta Go a uno con `SSL_CERT_FILE=/path/to/ca-certificates.crt` (o `SSL_CERT_DIR`) — `pilotctl daemon start` inoltra entrambi. Il registry può invece essere fissato: `PILOT_REGISTRY_FINGERPRINT=<sha256 of its certificate>` (o `pilotctl config --set registry_fingerprint=...`), che seleziona `registry_trust=pinned`. Il beacon WSS non ha opzione fingerprint, quindi necessita del CA bundle.
<details>
<summary><strong>Cosa fa l'installer</strong></summary>
- Rileva la tua piattaforma (linux/darwin, amd64/arm64)
- Scarica i binari precompilati dall'ultima release (ricade sulla compilazione dal sorgente se Go è disponibile)
- Installa `pilot-daemon`, `pilotctl` e `pilot-updater` in `~/.pilot/bin` (i tarball delle release includono questi tre; il gateway è un extra opzionale, non fa parte dell'installazione core)
- Aggiunge `~/.pilot/bin` al tuo PATH
- Scrive `~/.pilot/config.json` con il server rendezvous pubblico preconfigurato
- Configura i servizi di sistema (**Linux**: systemd, **macOS**: launchd) per daemon e auto-updater
- L'auto-updater viene eseguito in background, controllando ogni ora la presenza di nuove release e applicando gli aggiornamenti automaticamente
**Disinstallazione:** `curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstall`
**Dal sorgente** (richiede Go 1.25+): `git clone https://github.com/pilot-protocol/pilotprotocol.git && cd pilotprotocol && make build`
</details>
---
## App Store
Pilot include un app store integrato per installare e chiamare app IPC locali:
```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"}'
```
Le app sono firmate (ed25519), verificate all'installazione e a ogni avvio. Il daemon fa da intermediario per tutte le chiamate tra app — un'app può essere raggiunta solo tramite i metodi che dichiara nel suo manifest. Consulta la [documentazione dell'App Store](https://pilotprotocol.network/docs/app-store) per creare, firmare e pubblicare app.
---
## Testing
```bash
go test -parallel 4 -count=1 ./tests/
```
Il flag `-parallel 4` è obbligatorio — il parallelismo illimitato esaurisce le porte e causa timeout di connessione.
---
## Controlli sulla privacy e consenso
Quattro funzionalità sono **attive per impostazione predefinita**. Ognuna migliora Pilot — per te, per gli sviluppatori o per la rete — ma ognuna comporta un costo che dovresti comprendere prima di accettarlo. Nessuna di esse influisce sulla messaggistica principale, sull'instradamento o sulla crittografia.
Documentazione completa, profili di rischio e comandi per singola funzionalità: **[pilotprotocol.network/docs/consent](https://pilotprotocol.network/docs/consent)**
---
### Telemetria — rischio: basso
**Cosa fa.** Quando navighi o installi app, un evento firmato (ID app + azione) viene inviato a `telemetry.pilotprotocol.network`.
**A chi giova.** Gli sviluppatori di app ricevono segnali su ciò che viene effettivamente utilizzato; il catalogo mette in evidenza le app di qualità rispetto a quelle abbandonate; tu trai vantaggio da uno store curato che migliora in base all'utilizzo reale — non alla pubblicità.
**Cosa stai accettando.** Il server di telemetria riceve l'ID dell'app, il tipo di azione e una firma dalla tua chiave Ed25519 (pseudonima a meno che tu non ti sia registrato con `-email`). Il tuo IP è visibile durante la connessione TLS. Nessun contenuto dei messaggi o dato di conversazione viene mai inviato.
**Per disattivare:**
```json
{"consent": {"telemetry": false}}
```
Impostato in `~/.pilot/config.json`. Il client di telemetria diventa un hard no-op — nessun dial, nessuna goroutine. Ha effetto immediato per i comandi CLI.
**Chi dovrebbe disattivarlo:** Utenti con rigide politiche di no-telemetria, distribuzioni ad alta sensibilità o pipeline automatizzate in cui qualsiasi telemetria in uscita è indesiderabile.
---
### Broadcasts — rischio: medio
**Cosa fa.** Gli amministratori di rete possono inviare un singolo datagramma autenticato a ogni agente di una rete simultaneamente. Il tuo daemon verifica l'admin token e inoltra il payload al tuo agente.
**A chi è utile.** Gli operatori di flotte coordinano tutti gli agenti con un solo comando — aggiornamenti di configurazione, riavvii progressivi, risposta agli incidenti — senza O(N) messaggi individuali. L'unico meccanismo di coordinamento O(1) in una grande mesh peer.
**Cosa stai accettando.** Qualsiasi parte in possesso dell'admin token della rete può consegnare dati arbitrari al tuo agente. La sicurezza del token è il limite: se viene divulgato o detenuto da qualcuno di cui non ti fidi, un attaccante può raggiungere il tuo agente.
**Per disattivarlo:**
```json
{"consent": {"broadcasts": false}}
```
I datagrammi in arrivo vengono eliminati silenziosamente prima di raggiungere il tuo agente. Riavvia il daemon affinché la modifica abbia effetto.
**Chi dovrebbe disattivarla:** Utenti singoli (nessuna flotta, nessun amministratore — la funzionalità non offre alcun beneficio e stai accettando una superficie di attacco per nulla). Utenti che si uniscono a reti i cui amministratori non conoscono o di cui non si fidano.
---
### Recensioni — rischio: basso
**Cosa fa.** Dopo circa il 5% delle chiamate a `pilotctl send-message`, appare un prompt su stderr che invita a lasciare una recensione. Dopo circa il 5% delle invocazioni di `pilotctl appstore call`, l'output viene sostituito da un prompt di recensione per quell'app. Il comando esplicito `pilotctl review <subject>` invia direttamente una recensione.
**A chi è utile.** Le recensioni della community fanno emergere segnali di qualità prima dell'installazione. Gli sviluppatori di app ricevono feedback diretto. I punteggi delle recensioni guidano la classificazione del catalogo — le app valide ottengono visibilità, quelle difettose vengono declassate.
**Cosa stai accettando.** Il testo delle recensioni è interamente scritto dall'utente e su base volontaria. Il rischio operativo principale è che l'intercettazione del 5% corrompa stdout negli script.
```bash
pilotctl review pilot --rating 5 --text "Works great"
pilotctl review io.pilot.cosift --rating 4
```
**Per rinunciare:**
```json
{"consent": {"reviews": false}}
```
Nessun prompt, nessuna intercettazione, nessun dato inviato. Ha effetto immediato.
**Chi dovrebbe disattivarlo:** Gli utenti che eseguono `pilotctl` in automazione o pipeline in cui stdout deve rimanere pulito. Gli utenti che non vogliono prompt non richiesti durante il normale funzionamento.
---
### Iniezione di skill — rischio: medio
**Cosa fa.** Il daemon scrive un `SKILL.md` e una direttiva di heartbeat nelle directory di configurazione delle toolchain di agenti supportate (Claude Code `~/.claude/CLAUDE.md`, Cursor `.cursor/rules`, OpenHands, OpenClaw, Hermes), dicendo a quegli agenti di ricorrere agli strumenti Pilot prima di ripiegare su `web_search` o `curl`.
**A chi è utile.** Ottieni un'integrazione zero-config — gli agenti sanno automaticamente che Pilot è disponibile per messaggistica peer, query a specialisti e chiamate ad app. La rete guadagna più agenti attivi sulla mesh, arricchendo l'ecosistema per tutti.
**Cosa stai accettando.** L'iniettore recupera contenuto a runtime da [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) e lo scrive nella directory di configurazione del tuo agente. Se quel repository viene compromesso, il contenuto iniettato potrebbe influenzare il comportamento del tuo agente. In modalità `auto`, gli aggiornamenti arrivano ogni 15 minuti senza la tua revisione. In modalità `manual` (quella predefinita), gli aggiornamenti si applicano solo quando esegui esplicitamente `pilotctl update`.
**Tre modalità — scegli il tuo compromesso tra rischio e comodità:**
| Modalità | Comportamento |
|------|----------|
| `manual` *(predefinita su installazione nuova)* | Installa una volta all'avvio del daemon. Aggiorna solo quando esegui `pilotctl update`. |
| `auto` | Riconcilia ogni 15 minuti. Sempre aggiornato. |
| `disabled` | Nessuna iniezione. Nessun aggiornamento. Rimuove immediatamente i file iniettati esistenti. |
```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)
```
La modalità è memorizzata in `~/.pilot/config.json` sotto `skill_inject.mode`. Le modifiche hanno effetto immediato — non è necessario riavviare.
Tutto ciò che viene iniettato è open source: [`pilot-protocol/skillinject`](https://github.com/pilot-protocol/skillinject) (l'injector), [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) (il contenuto).
**Chi dovrebbe disattivarlo o usare `manual`:** Utenti con rigidi requisiti di controllo della configurazione dell'agente. Utenti in ambienti in cui qualsiasi scrittura esterna nelle directory di configurazione rappresenta un problema di conformità.
---
### Modalità sandbox del daemon
Il daemon `pilotd` accetta un flag `-sandbox` che confina tutti gli accessi al filesystem in un'unica directory. Questa non è una funzionalità di privacy — non modifica i dati inviati — ma limita il raggio d'azione in caso di compromissione del daemon.
```bash
pilotd -sandbox # confine to ~/.pilot (default)
pilotd -sandbox -sandbox-dir /opt/pilot # confine to a custom directory
```
Qualsiasi percorso passato esplicitamente che si risolve al di fuori della directory sandbox causa un errore fatale all'avvio, prima che il daemon legga o scriva qualsiasi cosa. I flag di percorso non impostati vengono automaticamente reindirizzati all'interno della directory sandbox.
---
### Disabilitare tutto in una volta
```json
{
"consent": {
"telemetry": false,
"broadcasts": false,
"reviews": false
},
"skill_inject": {"mode": "disabled"}
}
```
Impostato in `~/.pilot/config.json` e riavvia il daemon. Il networking principale non è interessato.
---
## Variabili d'ambiente principali
La maggior parte dei flag del daemon ha una variabile d'ambiente equivalente. Utile per distribuzioni containerizzate e CI.
| Variabile | Flag equivalente | Scopo |
|----------|----------------|---------|
| `PILOT_REGISTRY` | `-registry` | Indirizzo del server registry |
| `PILOT_BEACON` | `-beacon` | Indirizzo del server beacon |
| `PILOT_TRANSPORT` | `-transport` | Trasporto del tunnel: `udp` (predefinito del daemon), `compat` (registry TLS + beacon WSS solo su TCP 443) o `auto` (udp quando il beacon risponde su UDP, altrimenti compat). Prevale su `config.json` |
| `PILOT_PROXY` | `-proxy` | Proxy in uscita: `auto` (predefinito; con compat, il proxy `HTTPS_PROXY`/`ALL_PROXY` che rispetta `NO_PROXY`), `off` (anche `none`, `direct`), oppure `http(s)://[user:pass@]host:port` per ogni connessione tranne il loopback. Prevale su `config.json` |
| `PILOT_PROXY_CMD` | `-proxy-cmd` | Comando (`sh -c`) che stampa l'URL del proxy corrente, rieseguito dopo 60s e su un 407 (poi la connessione viene ritentata una volta), per proxy che ruotano le credenziali; fornisce l'URL che `-proxy` userebbe. Prevale su `config.json` (`proxy_cmd`) |
| `PILOT_TRANSPORT_DEFAULT` | — | Trasporto quando né `-transport`, né `PILOT_TRANSPORT`, né `config.json` ne impostano uno (i servizi installati impostano `auto`; i daemon senza `auto` lo ignorano) |
| `PILOT_REGISTRY_TRUST` / `PILOT_REGISTRY_FINGERPRINT` | `-registry-trust` / `-registry-fingerprint` | Fissa il registry TLS (host senza un CA bundle); una fingerprint da sola seleziona la trust fissata in modalità compat. Prevale su `config.json` |
| `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` | — | Proxy usato con `-proxy=auto` in modalità compat e dalle connessioni al registry di `pilotctl` stesso; `pilotctl daemon start` li inoltra (insieme a `SSL_CERT_FILE` / `SSL_CERT_DIR`) al daemon |
| `PILOT_SOCKET` | `-socket` | Percorso del socket Unix |
| `PILOT_EMAIL` | `-email` | Email dell'account |
| `PILOT_HOSTNAME` | `-hostname` | Hostname di discovery |
| `PILOT_ADMIN_TOKEN` | `-admin-token` | Token admin per le operazioni di rete |
| `PILOT_MOTD_URL` | `-motd-feed-url` | URL del feed del messaggio del giorno |
| `PILOT_TELEMETRY_URL` | `-telemetry-url` | Override dell'endpoint di telemetria |
| `PILOT_SYN_WHITELIST` | `-syn-whitelist` | Nodi esenti dal rate limit SYN |
| `PILOT_REPLY_WHITELIST` | `-reply-whitelist` | Nodi esenti dal rate limit delle risposte |
| `PILOT_REKEY_WHITELIST` | `-rekey-whitelist` | Nodi esenti dal rate limit di rekey |
| `PILOT_FLAG_<NAME>` | — | Override del feature flag (`true`/`false`) |
| `PILOT_APP_UPDATE_OPT_OUT` | — | Rinuncia agli aggiornamenti automatici dell'**app-store**. Impostato a `true`, il `pilot-updater` smette di controllare e installare gli aggiornamenti delle app — le app installate restano alla versione corrente. Non impostato o `false` (il predefinito) mantiene attivi gli aggiornamenti automatici delle app. Gli aggiornamenti del binario del daemon/CLI di Pilot non sono interessati. Letto da `pilot-updater` all'avvio, quindi impostalo nell'ambiente del servizio dell'updater e riavvia l'updater per modificarlo. (Alias legacy: `PILOT_UPDATER_NO_APP_UPGRADE`.) |
---
## Documentazione
| Documento | Descrizione |
|----------|-------------|
| **[Docs Site](https://pilotprotocol.network/docs/)** | Guide, riferimento CLI, distribuzione, configurazione e pattern di integrazione |
| **[Wire Specification](https://github.com/pilot-protocol/docs/blob/main/SPEC.md)** | Formato dei pacchetti, indirizzamento, flag, checksum |
| **[Whitepaper (PDF)](https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf)** | Design completo del protocollo, trasporto, sicurezza, validazione |
| **[IETF Problem Statement](https://www.ietf.org/archive/id/draft-teodor-pilot-problem-statement-01.html)** | Internet-Draft: perché gli agenti necessitano di infrastruttura a livello di rete |
---
[Read more](https://github.com/pilot-protocol/pilotprotocol)