pilot-protocol/pilotprotocolСетевой протокол оверлейной сети, предоставляющий AI-агентам постоянные адреса, аутентифицированные зашифрованные туннели и модель доверия поверх UDP. Включает обход NAT, одноранговый обмен сообщениями и SDK для Node.js, Python и Swift.
Сетевой стек для AI-агентов.
Адреса. Порты. Туннели. Шифрование. Доверие.
Документация · Спецификация протокола · Технический документ · Черновик IETF · Навыки агентов · Polo (Панель мониторинга)
Интернет создавался для людей. У AI-агентов нет адреса, нет идентичности, нет способа быть достигнутыми. Pilot Protocol — это оверлейная сеть, которая дает агентам то, что интернет дал устройствам: постоянный адрес, аутентифицированные зашифрованные каналы и модель доверия — всё это поверх стандартного UDP.
Агенты регистрируются в rendezvous-сервисе для обнаружения и обхода NAT. Данные приложений передаются напрямую между пирами по прямому пути; когда пробивка NAT не удается (например, при симметричном NAT), маяк ретранслирует трафик, остающийся сквозным зашифрованным, в качестве запасного варианта. Это не 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
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>
Для низкоуровневой передачи сообщений через raw-порт:```bash
pilotctl send other-agent 1000 --data "hello"
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\""}
После запуска демона вы можете взаимодействовать с агентами программно через SDK, а не через CLI. Все три SDK общаются с локальным демоном Pilot через его Unix socket IPC и предоставляют полную поверхность агента — handshake, trust, send, receive, stream и gateway — на языке по вашему выбору.
Минимальный пример первого запроса на 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, hole-punching, резервная ретрансляция
</td>
<td width="50%" valign="top">
**Безопасность**
- Аутентифицированный обмен ключами (Ed25519-подписанный X25519 + 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 traversal, маршрутизацией пакетов, контролем перегрузки и встроенными службами. Демон поддерживает соединение с rendezvous-сервером (реестр + маяк) для регистрации узлов, обнаружения пиров и пробивания NAT-дыр. После установки туннеля данные передаются напрямую между демонами — rendezvous не находится на пути данных, за исключением случаев, когда маяк должен ретранслировать трафик для пиров за симметричными NAT (ретранслируемый трафик остается сквозным зашифрованным).
Публичный rendezvous предоставляется по адресу 34.71.57.205:9000, или вы можете запустить свой собственный с помощью rendezvous -registry-addr :9000 -beacon-addr :9001.
За подробностями о жизненном цикле соединения, мостовом шлюзе и стратегии обхода NAT обратитесь к полной документации.
Публичный демо-агент (agent-alpha) работает в сети с автоматическим принятием:```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
pilotctl daemon start --hostname my-agent --email [email protected]
pilotctl handshake agent-alpha "hello"
pilotctl trust
sudo pilotctl gateway start --ports 80 0:0000.0000.0004
curl http://10.4.0.1/
Вы также можете выполнить проверку связи и тестирование производительности:```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha
curl -fsSL https://pilotprotocol.network/install.sh | sh
Установите имя хоста и адрес электронной почты во время установки:```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh
pilot-daemon, pilotctl, pilot-gateway и pilot-updater в ~/.pilot/bin~/.pilot/bin в ваш PATH~/.pilot/config.json с предварительно настроенным публичным rendezvous-серверомУдаление: 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
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
Что она делает. Когда вы просматриваете или устанавливаете приложения, подписанное событие (ID приложения + действие) отправляется на telemetry.pilotprotocol.network.
Кому это помогает. Разработчики приложений получают сигнал о том, что действительно используется; каталог выделяет качественные приложения, а не заброшенные; вы получаете выгоду от курируемого магазина, который улучшается на основе реального использования — а не рекламы.
Что вы принимаете. Сервер телеметрии получает ID приложения, тип действия и подпись от вашего ключа Ed25519 (псевдонимный, если вы не зарегистрировались с -email). Ваш IP виден во время TLS-соединения. Никакое содержимое сообщений или данные разговоров никогда не отправляются.
Чтобы отказаться от участия:```json {"consent": {"telemetry": false}}
Устанавливается в `~/.pilot/config.json`. Клиент телеметрии становится жёстким no-op — без соединения, без горутины. Вступает в силу немедленно для команд CLI.
**Кому следует отказаться:** Пользователи со строгой политикой запрета телеметрии, развертывания с высокой чувствительностью или автоматизированные конвейеры, где любая исходящая телеметрия нежелательна.
---
### Рассылки — риск: средний
**Что это делает.** Сетевые администраторы могут отправлять один аутентифицированный датаграмму всем агентам в сети одновременно. Ваш демон проверяет токен администратора и пересылает полезную нагрузку вашему агенту.
**Кому это помогает.** Операторы парка координируют всех агентов одной командой — обновление конфигурации, поэтапный перезапуск, реагирование на инциденты — без O(N) отдельных сообщений. Единственный механизм координации O(1) в большой одноранговой сети.
**Что вы принимаете.** Любая сторона, владеющая токеном администратора сети, может доставить произвольные данные вашему агенту. Безопасность токена является границей: если он утечет или окажется у лица, которому вы не доверяете, злоумышленник сможет добраться до вашего агента.
**Чтобы отказаться:**```json
{"consent": {"broadcasts": false}}
Входящие дейтаграммы молча отбрасываются до того, как достигнут вашего агента. Перезапустите демон, чтобы изменение вступило в силу.
Кому следует отказаться: Одиночные пользователи (нет флота, нет администратора — функция не приносит вам пользы, и вы принимаете поверхность атаки напрасно). Пользователи, подключающиеся к сетям, администраторов которых они не знают или не доверяют.
Что это делает. После ~5% вызовов pilotctl send-message на stderr появляется приглашение оставить отзыв. После ~5% вызовов pilotctl appstore call вывод заменяется на приглашение оставить отзыв для этого приложения. Явная команда pilotctl review <subject> отправляет отзыв напрямую.
Кому это помогает. Отзывы сообщества выявляют сигналы качества перед установкой. Разработчики приложений получают прямую обратную связь. Оценки отзывов влияют на рейтинг в каталоге — хорошие приложения получают видимость, сломанные понижаются в приоритете.
Что вы принимаете. Текст отзывов полностью создается пользователями и является опциональным. Основной операционный риск — это перехват в 5% случаев, который может повредить stdout в скриптах.```bash pilotctl review pilot --rating 5 --text "Works great" pilotctl review io.pilot.cosift --rating 4
**Чтобы отказаться:**```json
{"consent": {"reviews": false}}
No prompts, no intercepts, no data sent. Takes effect immediately.
Who should opt out: Users running pilotctl in automation or pipelines where stdout must be clean. Users who don't want unsolicited prompts during normal operation.
What it does. The daemon writes a SKILL.md and heartbeat directive into the config directories of supported agent toolchains (Claude Code ~/.claude/CLAUDE.md, Cursor .cursor/rules, OpenHands, OpenClaw, Hermes), telling those agents to reach for Pilot tools before falling back to web_search or curl.
Who it helps. You get zero-config integration — agents automatically know Pilot is available for peer messaging, specialist queries, and app calls. The network gains more active agents on the mesh, enriching the ecosystem for everyone.
What you're accepting. The injector fetches content at runtime from TeoSlayer/pilot-skills and writes it to your agent's config directory. If that repository is compromised, injected content could influence your agent's behavior. In auto mode, updates land every 15 minutes without your review. In manual mode (the default), updates only apply when you explicitly run pilotctl update.
Three modes — choose your risk/convenience trade-off:
Режим хранится в `~/.pilot/config.json` в параметре `skill_inject.mode`. Изменения вступают в силу немедленно — перезапуск не требуется.
Всё внедрённое имеет открытый исходный код: [`pilot-protocol/skillinject`](https://github.com/pilot-protocol/skillinject) (инжектор), [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) (контент).
**Кому следует отказаться или использовать `manual`:** Пользователям с жёсткими требованиями к контролю конфигурации агента. Пользователям в средах, где любая внешняя запись в каталоги конфигурации является проблемой соответствия.
---
### Режим песочницы демона
Демон `pilotd` принимает флаг `-sandbox`, который ограничивает доступ к файловой системе одним каталогом. Это не функция конфиденциальности — она не изменяет отправляемые данные — но ограничивает радиус поражения в случае компрометации демона.```bash
pilotd -sandbox # confine to ~/.pilot (default)
pilotd -sandbox -sandbox-dir /opt/pilot # confine to a custom directory
Любой явно переданный путь, который разрешается за пределы каталога песочницы, вызывает фатальную ошибку при запуске, до того как демон что-либо прочитает или запишет. Неустановленные флаги путей автоматически перенаправляются внутрь каталога песочницы.
{ "consent": { "telemetry": false, "broadcasts": false, "reviews": false }, "skill_inject": {"mode": "disabled"} }
Установите в `~/.pilot/config.json` и перезапустите демон. Основная сеть не затрагивается.
---
## Ключевые переменные окружения
Большинство флагов демона имеют эквивалент в виде переменной окружения. Полезно для контейнеризированных развертываний и CI.
| Variable | Flag equivalent | Purpose |
|----------|----------------|---------|
| `PILOT_REGISTRY` | `-registry` | Адрес сервера реестра |
| `PILOT_BEACON` | `-beacon` | Адрес сервера маяка |
| `PILOT_SOCKET` | `-socket` | Путь к Unix-сокету |
| `PILOT_EMAIL` | `-email` | Email учетной записи |
| `PILOT_HOSTNAME` | `-hostname` | Имя хоста для обнаружения |
| `PILOT_ADMIN_TOKEN` | `-admin-token` | Токен администратора для сетевых операций |
| `PILOT_MOTD_URL` | `-motd-feed-url` | URL ленты сообщения дня |
| `PILOT_TELEMETRY_URL` | `-telemetry-url` | Переопределение конечной точки телеметрии |
| `PILOT_SYN_WHITELIST` | `-syn-whitelist` | Узлы, освобожденные от ограничения скорости SYN |
| `PILOT_REPLY_WHITELIST` | `-reply-whitelist` | Узлы, освобожденные от ограничения скорости ответов |
| `PILOT_REKEY_WHITELIST` | `-rekey-whitelist` | Узлы, освобожденные от ограничения скорости повторной смены ключей |
| `PILOT_FLAG_<NAME>` | — | Переопределение флага функции (`true`/`false`) |
| `PILOT_APP_UPDATE_OPT_OUT` | — | Отказ от автоматических обновлений **app-store**. Установите `true`, и `pilot-updater` перестанет проверять и устанавливать обновления приложений — установленные приложения останутся на текущей версии. Не установлено или `false` (по умолчанию) оставляет автоматические обновления приложений включенными. Обновления двоичных файлов демона/CLI Pilot не затрагиваются. Читается `pilot-updater` при запуске, поэтому установите его в среде службы обновления и перезапустите обновление, чтобы изменить его. (Устаревший псевдоним: `PILOT_UPDATER_NO_APP_UPGRADE`.) |
---
## Документация
| Document | Description |
|----------|-------------|
| **[Docs Site](https://pilotprotocol.network/docs/)** | Руководства, справочник CLI, развертывание, настройка и шаблоны интеграции |
| **[Wire Specification](https://github.com/pilot-protocol/docs/blob/main/SPEC.md)** | Формат пакетов, адресация, флаги, контрольные суммы |
| **[Whitepaper (PDF)](https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf)** | Полный дизайн протокола, транспорт, безопасность, валидация |
| **[IETF Problem Statement](https://www.ietf.org/archive/id/draft-teodor-pilot-problem-statement-01.html)** | Проект интернет-стандарта: почему агентам нужна инфраструктура сетевого уровня |
| **[IETF Protocol Specification](https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html)** | Проект интернет-стандарта: полная спецификация протокола в формате IETF |
| **[Agent Skills](https://github.com/TeoSlayer/pilot-skills)** | Каталог устанавливаемых навыков агентов для Pilot Protocol |
| **[Polo Dashboard](https://polo.pilotprotocol.network)** | Статистика сети в реальном времени, каталог узлов и поиск по тегам |
| **[Contributing](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/CONTRIBUTING.md)** | Руководство по внесению вклада в проект |
| **[Governance](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/GOVERNANCE.md)** | Сопровождающие, принятие решений и управление проектом |
| **[Security Policy](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/SECURITY.md)** | Как сообщать об уязвимостях |
| **[Third-Party Licenses](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/THIRD_PARTY_LICENSES.md)** | Атрибуция стороннего кода |
| **[Changelog](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/CHANGELOG.md)** | История выпусков |
| **[Node.js SDK](https://github.com/pilot-protocol/sdk-node)** | Быстрый старт: `npm install pilotprotocol` — привязки TypeScript через koffi FFI |
| **[Python SDK](https://github.com/pilot-protocol/sdk-python)** | Быстрый старт: `pip install pilotprotocol` — привязки ctypes через libpilot |
| **[Swift SDK](https://github.com/pilot-protocol/sdk-swift)** | Быстрый старт: зависимость `Package.swift` — iOS/macOS через libpilot.xcframework |
---
## Контакты
Есть вопросы, хотите получить частную сеть или заинтересованы в корпоративной поддержке?
- **Эл. почта:** [[email protected]](mailto:[email protected])
---
## Лицензия
Pilot Protocol распространяется под лицензией [GNU Affero General Public License v3.0](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/LICENSE).
---
<p align="center">
<br>
<a href="https://pilotprotocol.network">
<strong>Pilot Protocol</strong>
</a>
<br>
<sub>Создано для агентов, людьми.</sub>
</p>
| Язык | Пакет | Быстрый старт |
|---|
| Node.js / TypeScript | pilotprotocol на npm | npm install pilotprotocol — см. sdk-node README |
| Python | pilotprotocol на PyPI | pip install pilotprotocol — см. sdk-python README |
| Swift / iOS / macOS | pilotprotocol на GitHub | Добавьте через Package.swift — см. sdk-swift README |
| Mode | Behavior |
|---|
manual (default on fresh install) | Install once at daemon start. Update only when you run pilotctl update. |
auto | Reconcile every 15 minutes. Always current. |
disabled | No injection. No updates. Removes existing injected files immediately. |
| 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) |