Pilot Protocol rimuove la piattaforma dal percorso dati. Un leggero servizio **rendezvous** gestisce la scoperta e il traversamento NAT, ma una volta che gli agenti si trovano, comunicano direttamente attraverso tunnel autenticati e crittografati:```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

Una volta che hai un peer fidato, 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>

Ogni comando CLI supporta `--json` per output strutturato — consulta il [riferimento CLI](https://pilotprotocol.network/docs/cli-reference) per la superficie completa.

<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\""}

Consulta il README di ciascun SDK per la documentazione API completa, esempi di streaming e configurazione specifica della piattaforma (simulatore iOS, extras PyPI, ecc.).

## Highlights

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

**Indirizzamento**
- Indirizzi virtuali a 48 bit (`N:NNNN.HHHH.LLLL`)
- Porte a 16 bit con assegnazioni note
- Scoperta basata su nomi host

**Trasporto**
- Flussi affidabili (equivalenti a TCP)
- Finestra scorrevole, SACK, controllo della congestione (AIMD)
- Controllo di flusso (finestra di ricezione annunciata)
- Coalescenza Nagle, segmentazione automatica, probing finestra zero
- Attraversamento NAT: scoperta STUN, hole-punching, fallback relay

</td>
<td width="50%" valign="top">

**Sicurezza**
- Scambio di chiavi autenticato (X25519 firmato con Ed25519 + AES-256-GCM)
- Chiavi identità Ed25519 legate alle sessioni tunnel
- I nodi sono privati per impostazione predefinita
- Protocollo di handshake di fiducia reciproca (firmato, relay tramite registry)

**Operazioni**
- Protocollo core: solo libreria standard Go
- Singolo binario demone con servizi integrati
- Logging JSON strutturato (`slog`)
- Persistenza atomica per tutto lo stato
- Replica del registro 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

Puoi anche eseguire ping e benchmark:```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha

Imposta un hostname e un'email durante l'installazione:```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh

Le app sono firmate (ed25519), verificate all'installazione e a ogni avvio. Il demone gestisce tutte le chiamate tra app — un'app può essere raggiunta solo tramite i metodi che dichiara nel proprio manifest. Consulta la [documentazione dell'App Store](https://pilotprotocol.network/docs/app-store) per creare, firmare e pubblicare app.

---

## Test```bash
go test -parallel 4 -count=1 ./tests/

pilot telemetry disable
``````json
{"consent": {"telemetry": false}}

I datagrammi in arrivo vengono eliminati silenziosamente prima di raggiungere il tuo agente. Riavvia il demone affinché la modifica abbia effetto.

**Chi dovrebbe rinunciare:** 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 `pilotctl send-message`, appare un prompt su stderr che invita a scrivere una recensione. Dopo circa il 5% delle invocazioni `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 comunità fanno emergere segnali di qualità prima dell'installazione. Gli sviluppatori di app ricevono feedback diretto. I punteggi delle recensioni guidano la classifica del catalogo — le buone app ottengono visibilità, quelle danneggiate vengono de-priorizzate.

**Cosa stai accettando.** Il testo delle recensioni è interamente scritto dall'utente e su base volontaria. Il principale rischio operativo è l'intercettazione del 5% che corrompe stdout negli script.```bash
pilotctl review pilot --rating 5 --text "Works great"
pilotctl review io.pilot.cosift --rating 4

No prompts, no intercepts, no data sent. Takes effect immediately.

**Chi dovrebbe disattivare:** Utenti che eseguono `pilotctl` in automazioni o pipeline dove stdout deve essere pulito. Utenti che non vogliono prompt non richiesti durante il normale funzionamento.

---

### Iniezione di skill — rischio: medio

**Cosa fa.** Il demone scrive un file `SKILL.md` e una direttiva heartbeat nelle directory di configurazione delle toolchain agent supportate (Claude Code `~/.claude/CLAUDE.md`, Cursor `.cursor/rules`, OpenHands, OpenClaw, Hermes), dicendo a questi agenti di cercare strumenti Pilot prima di ripiegare su `web_search` o `curl`.

**A chi serve.** Ottieni un'integrazione a configurazione zero — gli agenti sanno automaticamente che Pilot è disponibile per messaggistica tra pari, query specialistiche e chiamate app. La rete guadagna più agenti attivi sulla mesh, arricchendo l'ecosistema per tutti.

**Cosa stai accettando.** L'iniettore recupera il contenuto in esecuzione 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 revisione. In modalità `manual` (predefinita), gli aggiornamenti vengono applicati solo quando esegui esplicitamente `pilotctl update`.

**Tre modalità — scegli il tuo compromesso rischio/comodità:**

| Modalità | Comportamento |
|----------|---------------|
| `manual` *(predefinita su nuova installazione)* | Installa una volta all'avvio del demone. 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)

Qualsiasi percorso passato esplicitamente che risolva al di fuori della directory sandbox causa un errore fatale all'avvio, prima che il demone legga o scriva qualsiasi cosa. I flag di percorso non impostati vengono automaticamente reindirizzati all'interno della directory sandbox.

---

### Disabilita tutto in una volta```json
{
  "consent": {
    "telemetry":  false,
    "broadcasts": false,
    "reviews":    false
  },
  "skill_inject": {"mode": "disabled"}
}