pilot-protocol/pilotprotocolСетевой протокол оверлейной сети, предоставляющий AI-агентам постоянные адреса, аутентифицированные зашифрованные туннели и модель доверия поверх UDP. Включает обход NAT, одноранговый обмен сообщениями и SDK для Node.js, Python и 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>Сетевой стек для AI-агентов.</strong><br>
Адреса. Порты. Туннели. Шифрование. Доверие.
</p>
<p align="center">
<a href="https://pilotprotocol.network/docs/"><strong>Документация</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/SPEC.md"><strong>Спецификация протокола</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf"><strong>White paper</strong></a>
<span> · </span>
<a href="https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html"><strong>Черновик IETF</strong></a>
<span> · </span>
<a href="https://github.com/TeoSlayer/pilot-skills"><strong>Навыки агентов</strong></a>
<span> · </span>
<a href="https://polo.pilotprotocol.network"><strong>Polo (живая панель мониторинга)</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>
Интернет был создан для людей. У AI-агентов нет адреса, нет идентичности, нет способа, которым с ними можно связаться. Pilot Protocol — это оверлейная сеть, которая даёт агентам то, что интернет дал устройствам: **постоянный адрес, аутентифицированные зашифрованные каналы и модель доверия** — и всё это поверх стандартного UDP.
Агенты регистрируются в службе рандеву для обнаружения и обхода NAT. Данные приложений передаются напрямую между пирами по прямому пути; когда пробивка NAT не удаётся (например, при симметричном NAT), beacon ретранслирует всё ещё сквозным образом зашифрованный трафик в качестве запасного варианта. Это не API. Это не фреймворк. Это инфраструктура.
---
## Проблема
Сегодня агенты общаются через централизованные API. Каждое сообщение проходит через платформу — платформа видит весь трафик, контролирует доступ и становится единой точкой отказа.
```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
```
Pilot Protocol выводит платформу из пути передачи данных. Легковесный сервис **rendezvous** обеспечивает обнаружение и обход NAT, но как только агенты находят друг друга, они общаются напрямую через аутентифицированные зашифрованные туннели:
```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
```
## Что получают агенты
```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
```
Как только у вас появится доверенный узел, обмен сообщениями между агентами использует службу обмена данными на порту 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>
```
Для низкоуровневого обмена сообщениями через необработанные порты:
```bash
# on the sender
pilotctl send other-agent 1000 --data "hello"
# on the receiver
pilotctl recv 1000 --count 5 --timeout 30s
```
Каждая CLI-команда поддерживает `--json` для структурированного вывода — см. [справочник CLI](https://pilotprotocol.network/docs/cli-reference) для полного описания возможностей.
<details>
<summary><strong>Пример вывода 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>
---
## Программный доступ (SDK)
После запуска демона вы можете взаимодействовать с агентами программно через SDK вместо CLI. Все три SDK взаимодействуют с локальным демоном Pilot через IPC по Unix-сокету и предоставляют полный набор возможностей агента — рукопожатие, доверие, отправку, получение, потоковую передачу и шлюз — на выбранном вами языке.
| Язык | Пакет | Быстрый старт |
|----------|---------|------------|
| **Node.js / TypeScript** | [`pilotprotocol` на npm](https://www.npmjs.com/package/pilotprotocol) | `npm install pilotprotocol` — см. [sdk-node README](https://github.com/pilot-protocol/sdk-node) |
| **Python** | [`pilotprotocol` на PyPI](https://pypi.org/project/pilotprotocol/) | `pip install pilotprotocol` — см. [sdk-python README](https://github.com/pilot-protocol/sdk-python) |
| **Swift / iOS / macOS** | [`pilotprotocol` на GitHub](https://github.com/pilot-protocol/sdk-swift) | Добавьте через `Package.swift` — см. [sdk-swift README](https://github.com/pilot-protocol/sdk-swift) |
Минимальный пример первого запроса на Node.js после `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());
```
См. README каждого SDK для полной документации по API, примеров потоковой передачи и настройки под конкретную платформу (симулятор iOS, дополнительные пакеты PyPI и т. д.).
## Ключевые особенности
<table>
<tr>
<td width="50%" valign="top">
**Адресация**
- 48-битные виртуальные адреса (`N:NNNN.HHHH.LLLL`)
- 16-битные порты с общеизвестными назначениями
- Обнаружение на основе имён хостов
**Транспорт**
- Надёжные потоки (эквивалент TCP)
- Скользящее окно, SACK, управление перегрузкой (AIMD)
- Управление потоком (объявляемое окно приёма)
- Объединение по Нейглу, автосегментация, зондирование нулевого окна
- Обход NAT: обнаружение через STUN, пробивание отверстий, резервный ретранслятор
</td>
<td width="50%" valign="top">
**Безопасность**
- Аутентифицированный обмен ключами (X25519 с подписью Ed25519 + AES-256-GCM)
- Идентификационные ключи Ed25519, привязанные к сессиям туннеля
- Узлы по умолчанию приватны
- Протокол рукопожатия взаимного доверия (подписанный, ретрансляция через реестр)
**Эксплуатация**
- Ядро протокола: только стандартная библиотека Go
- Единый бинарник демона со встроенными сервисами
- Структурированное JSON-логирование (`slog`)
- Атомарное сохранение всего состояния
- Репликация реестра в режиме горячего резерва
</td>
</tr>
</table>
---
## Архитектура
```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
```
Ваш агент общается с локальным **демоном** через Unix-сокет. Демон отвечает за шифрование туннеля, обход NAT, маршрутизацию пакетов, управление перегрузкой и встроенные сервисы. Демон поддерживает соединение с **rendezvous**-сервером (реестр + beacon) для регистрации узлов, обнаружения пиров и пробивки NAT. После установки туннеля данные передаются напрямую между демонами -- rendezvous не находится на пути данных, за исключением случаев, когда beacon должен ретранслировать трафик для пиров за симметричными NAT (ретранслируемый трафик остаётся зашифрованным end-to-end).
Публичный rendezvous доступен по адресу `34.71.57.205:9000`, или вы можете запустить свой собственный с помощью `rendezvous -registry-addr :9000 -beacon-addr :9001`.
Подробности о жизненном цикле соединения, мостах шлюзов и стратегии обхода NAT см. в [полной документации](https://pilotprotocol.network/docs/).
---
## Демо
Публичный демо-агент (`agent-alpha`) работает в сети с включённым авто-принятием:
```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/
```
Вы также можете выполнить ping и бенчмарк:
```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha
```
---
## Установка
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
```
Укажите имя хоста и адрес электронной почты во время установки:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh
```
**UDP заблокирован, или единственный выход — это HTTPS-прокси** (изолированные песочницы размещённых агентов, такие как Meta Muse, заблокированные виртуальные машины)? Обычная установка работает:
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
pilotctl daemon start
```
Новые установки используют транспорт `auto`: демон один раз при запуске опрашивает beacon по UDP (один round trip, когда UDP работает, максимум ~1.5 с, когда нет) и, если ответа нет, но compat beacon отвечает по TCP 443 (TLS-запрос, на который живой beacon отвечает `426 Upgrade Required`), работает в режиме **compat** — registry по TLS на `registry.pilotprotocol.network:443`, beacon по WSS на `beacon.pilotprotocol.network:443`. Когда настроен прокси и он отклоняет эту проверку (неверные или устаревшие учётные данные: `407`, `403` или прокси недоступен), он всё равно работает в compat, а не откатывается к прямым соединениям в обход прокси, и тогда при дозвоне к registry указывается ответ прокси; `pilotctl daemon start` выводит последнюю ошибку прокси демона с подсказкой вместо просто «did not become ready». Когда ни один не отвечает и прокси не задействован (сети ещё нет, сбой beacon), он остаётся на UDP, как и раньше. В режиме compat демон туннелирует через `$HTTPS_PROXY` / `$ALL_PROXY` (с учётом `$NO_PROXY`), запрашивая у прокси `CONNECT` по имени хоста, так что отравленный локальный DNS для хостов Pilot не имеет значения. Собственные команды registry в `pilotctl` (`lookup`, проверка авто-рукопожатия, `recovery`) следуют за демоном: через прокси, когда он работает в compat (или при явном URL прокси), напрямую, когда он работает по UDP; когда демон не запущен и транспорт не настроен, они сначала пробуют прокси, а затем прямое соединение. Чтобы пропустить UDP-пробу, выберите compat явно: `sh -s -- --transport compat`, `pilotctl config --set transport=compat` или `pilotctl daemon start --transport compat`.
- **Не нужны root, systemd или launchd.** Запустите демон командой `pilotctl daemon start` из оболочки, в которой заданы переменные прокси. В контейнере или VM без systemd установщик также работает от root (пользователь агента в хостинговых песочницах); на обычном хосте он по-прежнему отказывается работать от root, если не задано `PILOT_ALLOW_ROOT=1`.
- **В контейнере дайте демону init-процесс.** Приложения запускают серверы, которые демонизируются (redis, postgres); демонизированный сервер передаётся PID 1, и когда он останавливается, он остаётся зомби (`Z` в `ps`), пока PID 1 его не соберёт. `pilot-daemon`, который сам является PID 1, этого не делает, поэтому зомби накапливаются и учитываются в лимите PID контейнера. Запускайте контейнер с `docker run --init` (Compose: `init: true`), сделайте [tini](https://github.com/krallin/tini) точкой входа (`ENTRYPOINT ["tini", "--", "pilot-daemon"]`) или в Kubernetes задайте `shareProcessNamespace: true` (ECS: `initProcessEnabled`). Демон регистрирует предупреждение при запуске, когда он является PID 1; отсутствие предупреждения не доказывает, что всё в порядке, если PID 1 — какой-то другой процесс без сбора потомков, например shell-скрипт. Он не собирает осиротевшие процессы сам: делать это внутри процесса означало бы также забирать статус завершения приложений, которыми он управляет.
- **Прокси с учётными данными:** держите их вне `ps` — экспортируйте `HTTPS_PROXY` / `PILOT_PROXY` или используйте `pilotctl daemon start --proxy http://user:pass@host:port` (pilotctl передаёт URL с учётными данными демону через его окружение, никогда в командной строке). Для службы systemd/launchd, которая не видит переменные вашей оболочки, сохраните его: `pilotctl config --set proxy=http://user:pass@host:port` (config.json имеет права 0600).
- **Учётные данные прокси, которые ротируются** (Meta Muse ротирует учётные данные в `HTTPS_PROXY` каждые несколько минут): долго работающий демон сохранял бы те, с которыми он запустился, и новые соединения начали бы падать с `407 Proxy Authentication Required`, пока старые туннели остаются активными («node online, apps broken»). Дайте демону команду, которая выводит текущий URL прокси — `proxy_cmd` в config.json, `$PILOT_PROXY_CMD`, `-proxy-cmd` или `pilotctl daemon start --proxy-cmd` — и он перезапускает её по прошествии 60 с и всякий раз, когда прокси отклоняет учётные данные (407 или искажённый ответ Muse «malformed HTTP status code»), повторяя это соединение один раз со свежими учётными данными (как для registry, так и для compat beacon и HTTP-клиентов, через обновление `netproxy` из common); перезапуск не нужен. Приложения, которые запускает демон, достигают прокси через loopback-ретранслятор в демоне, который добавляет текущие учётные данные, так что они продолжают работать и при ротациях. Собственные команды registry в pilotctl используют ту же команду. В Linux-контейнере/VM без systemd, где `HTTPS_PROXY` или `https_proxy` содержит учётные данные, `pilotctl daemon start` передаёт демону `PILOT_PROXY_CMD`, который выводит `$https_proxy` свежего bash (или `$HTTPS_PROXY`, когда учётные данные есть только в нём), когда `proxy_cmd` не настроен, и установщик сохраняет ту же команду в config.json; в остальных случаях: `pilotctl config --set proxy_cmd="bash -c 'printf %s \"\$https_proxy\"'"`. Без этого перезапускайте демон из свежей оболочки, когда он начинает падать.
- **Приоритет** для транспорта и прокси: флаг командной строки, затем `$PILOT_TRANSPORT` / `$PILOT_PROXY` / `$PILOT_PROXY_CMD`, затем `config.json` (`transport`, `proxy`, `proxy_cmd`), затем значение по умолчанию (`auto` от pilotctl и установленных служб systemd/launchd, через `PILOT_TRANSPORT_DEFAULT=auto`; `udp` для голого `pilot-daemon`; прокси `auto`). `auto` никогда не сохраняется в config.json, поэтому переустановка более старого релиза (`--version`, `pilotctl update --pin`) не оставляет ничего, что он не смог бы прочитать; если вы сохранили его сами, оба перезаписывают его в `udp` для демона, который предшествует ему. `-proxy` принимает `auto`, `off` (также `none`, `direct`) или URL `http://` / `https://`; всё остальное — ошибка. Loopback-цели (локальные webhooks, sidecar-ы) никогда не отправляются через прокси. Когда дозвон к registry идёт через прокси (compat или явный URL прокси в любом транспорте), стандартный raw-TCP registry заменяется на `registry.pilotprotocol.network:443` по TLS, поскольку CONNECT-прокси переносят только порт 443.
- **Нет CA-бандла в песочнице?** Укажите Go на него через `SSL_CERT_FILE=/path/to/ca-certificates.crt` (или `SSL_CERT_DIR`) — `pilotctl daemon start` передаёт оба. Вместо этого registry можно закрепить: `PILOT_REGISTRY_FINGERPRINT=<sha256 of its certificate>` (или `pilotctl config --set registry_fingerprint=...`), что выбирает `registry_trust=pinned`. У WSS beacon нет опции отпечатка, поэтому ему нужен CA-бандл.
<details>
<summary><strong>Что делает установщик</strong></summary>
- Определяет вашу платформу (linux/darwin, amd64/arm64)
- Скачивает готовые бинарники из последнего релиза (откатывается к сборке из исходников, если доступен Go)
- Устанавливает `pilot-daemon`, `pilotctl` и `pilot-updater` в `~/.pilot/bin` (в релизных tarball-ах поставляются эти три; gateway — опциональное дополнение, не часть основной установки)
- Добавляет `~/.pilot/bin` в ваш PATH
- Записывает `~/.pilot/config.json` с предварительно настроенным публичным rendezvous-сервером
- Настраивает системные службы (**Linux**: systemd, **macOS**: launchd) для демона и авто-обновлятора
- Авто-обновлятор работает в фоне, проверяя новые релизы каждый час и автоматически применяя обновления
**Удаление:** `curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstall`
**Из исходников** (требуется Go 1.25+): `git clone https://github.com/pilot-protocol/pilotprotocol.git && cd pilotprotocol && make build`
</details>
---
## App Store
Pilot включает встроенный магазин приложений для установки и вызова локальных IPC-приложений:
```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"}'
```
Приложения подписываются (ed25519), проверяются при установке и при каждом запуске. Демон выступает посредником для всех межприложенческих вызовов — к приложению можно обратиться только через методы, объявленные в его манифесте. См. [документацию App Store](https://pilotprotocol.network/docs/app-store) по созданию, подписыванию и публикации приложений.
---
## Тестирование
```bash
go test -parallel 4 -count=1 ./tests/
```
Флаг `-parallel 4` обязателен — неограниченный параллелизм исчерпывает порты и вызывает тайм-ауты при подключении.
---
## Управление конфиденциальностью и согласие
Четыре функции включены **по умолчанию**. Каждая из них улучшает Pilot — для вас, для разработчиков или для сети — но каждая несёт издержки, которые следует понимать, прежде чем их принимать. Ни одна из них не влияет на основные функции обмена сообщениями, маршрутизацию или шифрование.
Полная документация, профили рисков и команды для каждой функции: **[pilotprotocol.network/docs/consent](https://pilotprotocol.network/docs/consent)**
---
### Телеметрия — риск: низкий
**Что она делает.** Когда вы просматриваете или устанавливаете приложения, на `telemetry.pilotprotocol.network` отправляется подписанное событие (ID приложения + действие).
**Кому это помогает.** Разработчики приложений получают сигнал о том, что действительно используется; каталог выводит наверх качественные приложения вместо заброшенных; вы получаете выгоду от курируемого магазина, который улучшается на основе реального использования — а не рекламы.
**На что вы соглашаетесь.** Сервер телеметрии получает ID приложения, тип действия и подпись от вашего ключа Ed25519 (псевдонимную, если вы не регистрировались с `-email`). Ваш IP-адрес виден во время TLS-соединения. Содержимое сообщений или данные переписки никогда не отправляются.
**Чтобы отказаться:**
```json
{"consent": {"telemetry": false}}
```
Задаётся в `~/.pilot/config.json`. Клиент телеметрии становится жёстким no-op — без дозвона, без горутины. Вступает в силу немедленно для команд CLI.
**Кому стоит отказаться:** Пользователям со строгими политиками запрета телеметрии, высокочувствительным развёртываниям или автоматизированным конвейерам, где любая исходящая телеметрия нежелательна.
---
### Broadcasts — риск: средний
**Что это делает.** Сетевые администраторы могут отправить одну аутентифицированную датаграмму всем агентам в сети одновременно. Ваш демон проверяет админский токен и пересылает полезную нагрузку вашему агенту.
**Кому это помогает.** Операторы флота координируют всех агентов одной командой — обновления конфигурации, поэтапные перезапуски, реагирование на инциденты — без O(N) отдельных сообщений. Единственный механизм координации O(1) в крупной одноранговой сети.
**На что вы соглашаетесь.** Любая сторона, владеющая админским токеном сети, может доставить произвольные данные вашему агенту. Безопасность токена — это граница: если он утёк или находится у того, кому вы не доверяете, злоумышленник может добраться до вашего агента.
**Чтобы отказаться:**
```json
{"consent": {"broadcasts": false}}
```
Входящие датаграммы молча отбрасываются, не доходя до вашего агента. Перезапустите демон, чтобы изменения вступили в силу.
---
[Read more](https://github.com/pilot-protocol/pilotprotocol)