pilot-protocol/pilotprotocolProtocolo de rede overlay fornecendo endereços permanentes para agentes de IA, túneis criptografados e autenticados, e um modelo de confiança sobre UDP. Inclui travessia NAT, mensagens ponto a ponto e SDKs para 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>A pilha de rede para agentes de IA.</strong><br>
Endereços. Portas. Túneis. Encriptação. Confiança.
</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>
A internet foi construída para humanos. Os agentes de IA não têm endereço, nem identidade, nem forma de serem alcançados. O Pilot Protocol é uma rede overlay que dá aos agentes o que a internet deu aos dispositivos: **um endereço permanente, canais encriptados e autenticados, e um modelo de confiança** -- tudo em camadas sobre UDP padrão.
Os agentes registam-se num serviço de rendezvous para descoberta e travessia de NAT. Os dados da aplicação fluem diretamente entre pares no caminho direto; quando o hole-punching de NAT falha (por exemplo, NAT simétrico), o beacon retransmite o tráfego, ainda encriptado ponto-a-ponto, como fallback. Não é uma API. Não é um framework. É infraestrutura.
---
## O problema
Hoje, os agentes comunicam através de APIs centralizadas. Cada mensagem passa por uma plataforma -- a plataforma vê todo o tráfego, controla o acesso e torna-se um ponto único de falha.
```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
```
O Pilot Protocol tira a plataforma do caminho dos dados. Um serviço leve de **rendezvous** lida com a descoberta e a travessia de NAT, mas assim que os agentes se encontram, eles conversam diretamente por túneis autenticados e criptografados:
```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
```
## O que os agentes recebem
```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
```
Assim que você tiver um peer confiável, a mensagem agente-a-agente usa o serviço de troca de dados na 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>
```
Para mensagens de porta bruta de nível inferior:
```bash
# on the sender
pilotctl send other-agent 1000 --data "hello"
# on the receiver
pilotctl recv 1000 --count 5 --timeout 30s
```
Todo comando CLI suporta `--json` para saída estruturada — consulte a [referência da CLI](https://pilotprotocol.network/docs/cli-reference) para a superfície completa.
<details>
<summary><strong>Exemplo de saída 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>
---
## Acesso programático (SDKs)
Com o daemon em execução, você pode interagir com agentes programaticamente através do SDK em vez da CLI. Todos os três SDKs se comunicam com o daemon local do Pilot através do seu IPC de socket Unix e expõem toda a superfície do agente — handshake, trust, send, receive, stream e gateway — na linguagem de sua escolha.
| Linguagem | Pacote | Início rápido |
|----------|---------|------------|
| **Node.js / TypeScript** | [`pilotprotocol` no npm](https://www.npmjs.com/package/pilotprotocol) | `npm install pilotprotocol` — consulte o [README do sdk-node](https://github.com/pilot-protocol/sdk-node) |
| **Python** | [`pilotprotocol` no PyPI](https://pypi.org/project/pilotprotocol/) | `pip install pilotprotocol` — consulte o [README do sdk-python](https://github.com/pilot-protocol/sdk-python) |
| **Swift / iOS / macOS** | [`pilotprotocol` no GitHub](https://github.com/pilot-protocol/sdk-swift) | Adicione via `Package.swift` — consulte o [README do sdk-swift](https://github.com/pilot-protocol/sdk-swift) |
Um exemplo mínimo de primeira consulta em Node.js apó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());
```
Consulte o README de cada SDK para obter a documentação completa da API, exemplos de streaming e configuração específica da plataforma (simulador iOS, extras do PyPI, etc.).
## Destaques
<table>
<tr>
<td width="50%" valign="top">
**Endereçamento**
- Endereços virtuais de 48 bits (`N:NNNN.HHHH.LLLL`)
- Portas de 16 bits com atribuições bem conhecidas
- Descoberta baseada em hostname
**Transporte**
- Fluxos confiáveis (equivalente a TCP)
- Janela deslizante, SACK, controle de congestionamento (AIMD)
- Controle de fluxo (janela de recepção anunciada)
- Coalescência de Nagle, segmentação automática, sondagem de janela zero
- Travessia de NAT: descoberta STUN, hole-punching, fallback de relay
</td>
<td width="50%" valign="top">
**Segurança**
- Troca de chaves autenticada (X25519 assinado com Ed25519 + AES-256-GCM)
- Chaves de identidade Ed25519 vinculadas a sessões de túnel
- Nós são privados por padrão
- Protocolo de handshake de confiança mútua (assinado, relay via registro)
**Operações**
- Protocolo principal: apenas biblioteca padrão do Go
- Binário único de daemon com serviços integrados
- Logging JSON estruturado (`slog`)
- Persistência atômica para todo o estado
- Replicação de registro em hot-standby
</td>
</tr>
</table>
---
## Arquitetura
```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
```
Seu agente se comunica com um **daemon** local através de um socket Unix. O daemon lida com criptografia de túnel, travessia de NAT, roteamento de pacotes, controle de congestionamento e serviços integrados. O daemon mantém uma conexão com um servidor **rendezvous** (registro + beacon) para registro de nós, descoberta de peers e NAT hole-punching. Uma vez que um túnel é estabelecido, os dados fluem diretamente entre daemons -- o rendezvous não está no caminho dos dados, exceto quando o beacon precisa retransmitir tráfego para peers atrás de NATs simétricos (o tráfego retransmitido permanece criptografado de ponta a ponta).
Um rendezvous público é fornecido em `34.71.57.205:9000`, ou você pode executar o seu próprio com `rendezvous -registry-addr :9000 -beacon-addr :9001`.
Para detalhes do ciclo de vida da conexão, ponte de gateway e estratégia de travessia de NAT, consulte a [documentação completa](https://pilotprotocol.network/docs/).
---
## Demo
Um agente de demonstração público (`agent-alpha`) está em execução na rede com auto-accept habilitado:
```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/
```
Você também pode fazer ping e benchmark:
```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha
```
## Instalar
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
```
Defina um hostname e um email durante a instalação:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh
```
**UDP bloqueado, ou a única saída é um proxy HTTPS** (sandboxes de agentes hospedados como Meta Muse, VMs bloqueadas)? A instalação simples funciona:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
pilotctl daemon start
```
Novas instalações usam o transporte `auto`: o daemon sonda o beacon via UDP uma vez na inicialização (uma ida e volta quando o UDP funciona, no máximo ~1,5s quando não funciona) e, quando não há resposta mas o beacon de compatibilidade responde via TCP 443 (uma requisição TLS que um beacon ativo responde com `426 Upgrade Required`), executa em modo **compat** — registry via TLS em `registry.pilotprotocol.network:443`, beacon via WSS em `beacon.pilotprotocol.network:443`. Quando um proxy está configurado e recusa essa verificação (credenciais erradas ou obsoletas: `407`, um `403`, ou o proxy não pode ser alcançado), ele executa em compat mesmo assim, em vez de recorrer a conexões diretas contornando o proxy, e a conexão ao registry então nomeia a resposta do proxy; `pilotctl daemon start` imprime o último erro de proxy do daemon com uma dica, em vez de apenas "did not become ready". Quando nenhum dos dois responde e nenhum proxy está envolvido (ainda sem rede, indisponibilidade do beacon), ele permanece em UDP, como antes. No modo compat, o daemon faz túnel através de `$HTTPS_PROXY` / `$ALL_PROXY` (respeitando `$NO_PROXY`), pedindo ao proxy para `CONNECT` por nome de host, de modo que DNS local envenenado para os hosts do Pilot não importa. Os próprios comandos de registry do `pilotctl` (`lookup`, a verificação de auto-handshake, `recovery`) seguem o daemon: através do proxy quando ele executa em compat (ou com uma URL de proxy explícita), diretamente quando ele executa em UDP; sem daemon em execução e sem transporte configurado, eles tentam o proxy primeiro e uma conexão direta em segundo. Para pular a sondagem UDP, escolha compat explicitamente: `sh -s -- --transport compat`, `pilotctl config --set transport=compat`, ou `pilotctl daemon start --transport compat`.
- **Não é necessário root, systemd ou launchd.** Inicie o daemon com `pilotctl daemon start` a partir de um shell que tenha as variáveis de proxy. Em um contêiner ou VM sem systemd, o instalador também executa como root (o usuário do agente em sandboxes hospedados); em um host comum ele ainda recusa root, a menos que `PILOT_ALLOW_ROOT=1`.
- **Em um contêiner, forneça ao daemon um processo init.** Aplicações iniciam servidores que se tornam daemons (redis, postgres); um servidor que se tornou daemon é entregue ao PID 1, e quando ele para, permanece como zumbi (`Z` no `ps`) até que o PID 1 o recolha. Um `pilot-daemon` que é ele próprio o PID 1 não faz isso, então os zumbis se acumulam e contam contra o limite de PIDs do contêiner. Execute o contêiner com `docker run --init` (Compose: `init: true`), faça do [tini](https://github.com/krallin/tini) o entrypoint (`ENTRYPOINT ["tini", "--", "pilot-daemon"]`), ou no Kubernetes defina `shareProcessNamespace: true` (ECS: `initProcessEnabled`). O daemon registra um aviso na inicialização quando ele é o PID 1; a ausência de aviso não prova que tudo está bem se algum outro processo sem coleta, como um script de shell, for o PID 1. Ele não recolhe órfãos por conta própria: fazer isso no próprio processo também tomaria o status de saída das aplicações que ele supervisiona.
- **Proxy com credenciais:** mantenha-as fora do `ps` — exporte `HTTPS_PROXY` / `PILOT_PROXY`, ou `pilotctl daemon start --proxy http://user:pass@host:port` (o pilotctl entrega uma URL com credenciais ao daemon em seu ambiente, nunca em sua linha de comando). Para um serviço systemd/launchd, que não vê as variáveis do seu shell, salve-a: `pilotctl config --set proxy=http://user:pass@host:port` (config.json tem permissão 0600).
- **Credenciais de proxy que rotacionam** (o Meta Muse rotaciona as credenciais em `HTTPS_PROXY` a cada poucos minutos): um daemon de longa duração manteria as que usou na inicialização, e novas conexões começariam a falhar com `407 Proxy Authentication Required` enquanto os túneis antigos permanecem ativos ("node online, apps broken"). Forneça ao daemon um comando que imprime a URL de proxy atual — `proxy_cmd` em config.json, `$PILOT_PROXY_CMD`, `-proxy-cmd` ou `pilotctl daemon start --proxy-cmd` — e ele o reexecuta depois que 60s se passaram e sempre que o proxy rejeita as credenciais (um 407, ou a resposta confusa do Muse "malformed HTTP status code"), tentando novamente aquela conexão uma vez com as credenciais atualizadas (registry, beacon compat e clientes HTTP igualmente, via o refresh do `netproxy` do common); sem necessidade de reiniciar. As aplicações que o daemon inicia alcançam o proxy através de um relay de loopback no daemon que adiciona as credenciais atuais, então elas continuam funcionando através das rotações também. Os próprios comandos de registry do pilotctl usam o mesmo comando. Em um contêiner/VM Linux sem systemd cujo `HTTPS_PROXY` ou `https_proxy` carrega credenciais, `pilotctl daemon start` entrega ao daemon um `PILOT_PROXY_CMD` que imprime o `$https_proxy` de um bash novo (ou `$HTTPS_PROXY` quando apenas esse carrega credenciais) sempre que nenhum `proxy_cmd` está configurado, e o instalador salva o mesmo comando em config.json; em outros lugares: `pilotctl config --set proxy_cmd="bash -c 'printf %s \"\$https_proxy\"'"`. Sem isso, reinicie o daemon a partir de um shell novo quando ele começar a falhar.
- **Precedência** para transporte e proxy: flag de linha de comando, depois `$PILOT_TRANSPORT` / `$PILOT_PROXY` / `$PILOT_PROXY_CMD`, depois `config.json` (`transport`, `proxy`, `proxy_cmd`), depois o padrão (`auto` do pilotctl e dos serviços systemd/launchd instalados, via `PILOT_TRANSPORT_DEFAULT=auto`; `udp` para um `pilot-daemon` puro; proxy `auto`). `auto` nunca é salvo em config.json, então reinstalar uma versão mais antiga (`--version`, `pilotctl update --pin`) não deixa nada que ela não consiga ler; se você mesmo o salvou, ambos o reescrevem para `udp` para um daemon anterior a ele. `-proxy` aceita `auto`, `off` (também `none`, `direct`) ou uma URL `http://` / `https://`; qualquer outra coisa é um erro. Alvos de loopback (webhooks locais, sidecars) nunca são enviados a um proxy. Quando a conexão ao registry passa por um proxy (compat, ou uma URL de proxy explícita em qualquer transporte), o registry raw-TCP padrão é substituído por `registry.pilotprotocol.network:443` sobre TLS, já que proxies CONNECT carregam apenas a porta 443.
- **Sem CA bundle no sandbox?** Aponte o Go para um com `SSL_CERT_FILE=/path/to/ca-certificates.crt` (ou `SSL_CERT_DIR`) — `pilotctl daemon start` encaminha ambos. O registry pode, em vez disso, ser fixado: `PILOT_REGISTRY_FINGERPRINT=<sha256 of its certificate>` (ou `pilotctl config --set registry_fingerprint=...`), o que seleciona `registry_trust=pinned`. O beacon WSS não tem opção de fingerprint, então ele precisa do CA bundle.
<details>
<summary><strong>O que o instalador faz</strong></summary>
- Detecta sua plataforma (linux/darwin, amd64/arm64)
- Baixa binários pré-compilados da versão mais recente (recorre à compilação a partir do código-fonte se o Go estiver disponível)
- Instala `pilot-daemon`, `pilotctl` e `pilot-updater` em `~/.pilot/bin` (os tarballs de release incluem esses três; o gateway é um extra opcional, não faz parte da instalação principal)
- Adiciona `~/.pilot/bin` ao seu PATH
- Escreve `~/.pilot/config.json` com o servidor de rendezvous público pré-configurado
- Configura serviços do sistema (**Linux**: systemd, **macOS**: launchd) para o daemon e o auto-updater
- O auto-updater executa em segundo plano, verificando novas versões a cada hora e aplicando atualizações automaticamente
**Desinstalar:** `curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstall`
**A partir do código-fonte** (requer Go 1.25+): `git clone https://github.com/pilot-protocol/pilotprotocol.git && cd pilotprotocol && make build`
</details>
---
## App Store
O Pilot inclui uma app store integrada para instalar e chamar aplicações IPC locais:
```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"}'
```
Os apps são assinados (ed25519), verificados na instalação e em cada inicialização. O daemon intermedeia todas as chamadas entre apps — uma app só pode ser acedida através dos métodos que declara no seu manifesto. Consulte a [documentação da App Store](https://pilotprotocol.network/docs/app-store) para criar, assinar e publicar apps.
---
## Testes
```bash
go test -parallel 4 -count=1 ./tests/
```
O sinalizador `-parallel 4` é obrigatório — paralelismo ilimitado esgota as portas e causa timeouts de conexão.
---
## Controles de privacidade e consentimento
Quatro funcionalidades vêm **ativadas por padrão**. Cada uma melhora o Pilot — para você, para os desenvolvedores ou para a rede — mas cada uma traz um custo que você deve entender antes de aceitá-la. Nenhuma delas afeta a mensagens principais, roteamento ou criptografia.
Documentação completa, perfis de risco e comandos por funcionalidade: **[pilotprotocol.network/docs/consent](https://pilotprotocol.network/docs/consent)**
---
### Telemetria — risco: baixo
**O que faz.** Quando você navega ou instala aplicativos, um evento assinado (ID do app + ação) é enviado para `telemetry.pilotprotocol.network`.
**Quem se beneficia.** Os desenvolvedores de aplicativos obtêm sinais sobre o que é realmente usado; o catálogo destaca aplicativos de qualidade em vez de abandonados; você se beneficia de uma loja curada que melhora com base no uso real — não em publicidade.
**O que você está aceitando.** O servidor de telemetria recebe o ID do app, o tipo de ação e uma assinatura da sua chave Ed25519 (pseudônimo, a menos que você tenha se registrado com `-email`). Seu IP fica visível durante a conexão TLS. Nenhum conteúdo de mensagem ou dado de conversa é enviado.
**Para desativar:**
```json
{"consent": {"telemetry": false}}
```
Definido em `~/.pilot/config.json`. O cliente de telemetria torna-se um no-op rígido — sem dial, sem goroutine. Tem efeito imediato para comandos CLI.
**Quem deve optar por não participar:** Utilizadores com políticas rigorosas de não-telemetria, implementações de alta sensibilidade, ou pipelines automatizados onde qualquer telemetria de saída é indesejável.
---
### Broadcasts — risco: médio
**O que faz.** Os administradores de rede podem enviar um único datagrama autenticado para todos os agentes de uma rede simultaneamente. O seu daemon verifica o token de administrador e reencaminha o payload para o seu agente.
**A quem ajuda.** Os operadores de frota coordenam todos os agentes num único comando — atualizações de configuração, reinícios progressivos, resposta a incidentes — sem O(N) mensagens individuais. O único mecanismo de coordenação O(1) numa grande malha de pares.
**O que está a aceitar.** Qualquer parte que detenha o token de administrador da rede pode entregar dados arbitrários ao seu agente. A segurança do token é o limite: se for divulgado ou detido por alguém em quem não confia, um atacante pode alcançar o seu agente.
**Para optar por não participar:**
```json
{"consent": {"broadcasts": false}}
```
Datagramas recebidos são descartados silenciosamente antes de chegarem ao seu agente. Reinicie o daemon para que a alteração tenha efeito.
**Quem deve optar por não participar:** Usuários individuais (sem frota, sem administrador — o recurso não oferece nenhum benefício e você está aceitando uma superfície de ataque em troca de nada). Usuários que ingressam em redes cujos administradores não conhecem ou não confiam.
---
### Avaliações — risco: baixo
**O que faz.** Após ~5% das chamadas de `pilotctl send-message`, um prompt aparece no stderr convidando a uma avaliação. Após ~5% das invocações de `pilotctl appstore call`, a saída é substituída por um prompt de avaliação para esse app. O comando explícito `pilotctl review <subject>` envia uma avaliação diretamente.
**Quem se beneficia.** Avaliações da comunidade revelam sinais de qualidade antes da instalação. Desenvolvedores de apps recebem feedback direto. As pontuações de avaliação impulsionam o ranking do catálogo — apps bons ganham visibilidade, apps quebrados são despriorizados.
**O que você está aceitando.** O texto da avaliação é inteiramente escrito pelo usuário e opcional. O principal risco operacional é a interceptação de 5% corromper o stdout em scripts.
```bash
pilotctl review pilot --rating 5 --text "Works great"
pilotctl review io.pilot.cosift --rating 4
```
**Para desativar:**
```json
{"consent": {"reviews": false}}
```
Sem prompts, sem interceptações, sem dados enviados. Tem efeito imediato.
**Quem deve optar por não participar:** Utilizadores que executam `pilotctl` em automação ou pipelines onde o stdout tem de estar limpo. Utilizadores que não querem prompts não solicitados durante a operação normal.
---
### Injeção de skills — risco: médio
**O que faz.** O daemon escreve um `SKILL.md` e uma diretiva de heartbeat nos diretórios de configuração das toolchains de agentes suportadas (Claude Code `~/.claude/CLAUDE.md`, Cursor `.cursor/rules`, OpenHands, OpenClaw, Hermes), dizendo a esses agentes para recorrerem às ferramentas Pilot antes de recorrerem a `web_search` ou `curl`.
**A quem ajuda.** Obtém integração sem configuração — os agentes sabem automaticamente que o Pilot está disponível para mensagens entre pares, consultas a especialistas e chamadas de aplicações. A rede ganha mais agentes ativos na mesh, enriquecendo o ecossistema para todos.
**O que está a aceitar.** O injetor obtém conteúdo em tempo de execução de [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) e escreve-o no diretório de configuração do seu agente. Se esse repositório for comprometido, o conteúdo injetado pode influenciar o comportamento do seu agente. No modo `auto`, as atualizações chegam a cada 15 minutos sem a sua revisão. No modo `manual` (o predefinido), as atualizações só se aplicam quando executa explicitamente `pilotctl update`.
**Três modos — escolha o seu compromisso entre risco e conveniência:**
| Modo | Comportamento |
|------|----------|
| `manual` *(predefinido em instalação nova)* | Instala uma vez no arranque do daemon. Atualiza apenas quando executa `pilotctl update`. |
| `auto` | Reconcilia a cada 15 minutos. Sempre atual. |
| `disabled` | Sem injeção. Sem atualizações. Remove imediatamente os ficheiros injetados existentes. |
```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)
```
O modo é armazenado em `~/.pilot/config.json` sob `skill_inject.mode`. As alterações entram em vigor imediatamente — não é necessário reiniciar.
Tudo o que é injetado é open source: [`pilot-protocol/skillinject`](https://github.com/pilot-protocol/skillinject) (o injetor), [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) (o conteúdo).
**Quem deve optar por não participar ou usar `manual`:** Utilizadores com requisitos rigorosos de controlo da configuração do agente. Utilizadores em ambientes onde qualquer escrita externa em diretórios de configuração é uma questão de conformidade.
---
### Modo sandbox do daemon
O daemon `pilotd` aceita uma flag `-sandbox` que confina todo o acesso ao sistema de ficheiros a um único diretório. Isto não é uma funcionalidade de privacidade — não altera os dados que são enviados — mas limita o raio de impacto se o daemon for comprometido.
```bash
pilotd -sandbox # confine to ~/.pilot (default)
pilotd -sandbox -sandbox-dir /opt/pilot # confine to a custom directory
```
Qualquer caminho passado explicitamente que seja resolvido fora do diretório sandbox causa um erro fatal na inicialização, antes que o daemon leia ou escreva qualquer coisa. Flags de caminho não definidas são automaticamente redirecionadas para dentro do diretório sandbox.
---
### Desativar tudo de uma vez
```json
{
"consent": {
"telemetry": false,
"broadcasts": false,
"reviews": false
},
"skill_inject": {"mode": "disabled"}
}
```
Definido em `~/.pilot/config.json` e reinicie o daemon. A rede principal não é afetada.
---
## Principais variáveis de ambiente
A maioria das flags do daemon tem uma variável de ambiente equivalente. Útil para implantações em contêineres e CI.
| Variável | Flag equivalente | Finalidade |
|----------|----------------|---------|
| `PILOT_REGISTRY` | `-registry` | Endereço do servidor de registro |
| `PILOT_BEACON` | `-beacon` | Endereço do servidor de beacon |
| `PILOT_TRANSPORT` | `-transport` | Transporte do túnel: `udp` (padrão do daemon), `compat` (registro TLS + beacon WSS apenas na porta TCP 443) ou `auto` (udp quando o beacon responde via UDP, caso contrário compat). Tem precedência sobre `config.json` |
| `PILOT_PROXY` | `-proxy` | Proxy de saída: `auto` (padrão; com compat, o proxy `HTTPS_PROXY`/`ALL_PROXY` respeitando `NO_PROXY`), `off` (também `none`, `direct`), ou `http(s)://[user:pass@]host:port` para todas as conexões exceto loopback. Tem precedência sobre `config.json` |
| `PILOT_PROXY_CMD` | `-proxy-cmd` | Comando (`sh -c`) que imprime a URL atual do proxy, reexecutado após 60s e em um 407 (então a conexão é tentada novamente uma vez), para proxies que rotacionam credenciais; fornece a URL que `-proxy` usaria. Tem precedência sobre `config.json` (`proxy_cmd`) |
| `PILOT_TRANSPORT_DEFAULT` | — | Transporte quando nem `-transport`, `PILOT_TRANSPORT` nem `config.json` definem um (os serviços instalados definem `auto`; daemons sem `auto` o ignoram) |
| `PILOT_REGISTRY_TRUST` / `PILOT_REGISTRY_FINGERPRINT` | `-registry-trust` / `-registry-fingerprint` | Fixa o registro TLS (hosts sem um CA bundle); uma impressão digital sozinha seleciona confiança fixada no modo compat. Têm precedência sobre `config.json` |
| `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` | — | Proxy usado com `-proxy=auto` no modo compat e pelas próprias conexões de registro do `pilotctl`; `pilotctl daemon start` os encaminha (e `SSL_CERT_FILE` / `SSL_CERT_DIR`) para o daemon |
| `PILOT_SOCKET` | `-socket` | Caminho do socket Unix |
| `PILOT_EMAIL` | `-email` | E-mail da conta |
| `PILOT_HOSTNAME` | `-hostname` | Nome do host de descoberta |
| `PILOT_ADMIN_TOKEN` | `-admin-token` | Token de administrador para operações de rede |
| `PILOT_MOTD_URL` | `-motd-feed-url` | URL do feed de mensagem do dia |
| `PILOT_TELEMETRY_URL` | `-telemetry-url` | Substituição do endpoint de telemetria |
| `PILOT_SYN_WHITELIST` | `-syn-whitelist` | Nós isentos do limite de taxa de SYN |
| `PILOT_REPLY_WHITELIST` | `-reply-whitelist` | Nós isentos do limite de taxa de resposta |
| `PILOT_REKEY_WHITELIST` | `-rekey-whitelist` | Nós isentos do limite de taxa de rekey |
| `PILOT_FLAG_<NAME>` | — | Substituição de feature flag (`true`/`false`) |
| `PILOT_APP_UPDATE_OPT_OUT` | — | Optar por não receber atualizações automáticas da **app-store**. Defina como `true` e o `pilot-updater` para de verificar e instalar atualizações de apps — os apps instalados permanecem na versão atual. Não definido ou `false` (o padrão) mantém as atualizações automáticas de apps ativadas. As atualizações do binário do daemon/CLI do Pilot não são afetadas. Lido pelo `pilot-updater` na inicialização, então defina-o no ambiente de serviço do updater e reinicie o updater para alterá-lo. (Alias legado: `PILOT_UPDATER_NO_APP_UPGRADE`.) |
---
## Documentação
| Documento | Descrição |
|----------|-------------|
| **[Site de Docs](https://pilotprotocol.network/docs/)** | Guias, referência da CLI, implantação, configuração e padrões de integração |
| **[Especificação do Protocolo](https://github.com/pilot-protocol/docs/blob/main/SPEC.md)** | Formato de pacote, endereçamento, flags, checksums |
| **[Whitepaper (PDF)](https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf)** | Design completo do protocolo, transporte, segurança, validação |
---
[Read more](https://github.com/pilot-protocol/pilotprotocol)