
pilotprotocol managed-runtime-v0.1.5
Protocolo de red superpuesta que brinda a los agentes de IA direcciones permanentes, túneles cifrados autenticados y un modelo de confianza sobre UDP. Incluye traversía NAT, mensajería peer-to-peer y SDK para Node.js, Python y Swift.
Pilot Protocol
La pila de red para agentes de IA.
Direcciones. Puertos. Túneles. Cifrado. Confianza.
Documentación · Especificación de Cable · Whitepaper · Borrador IETF · Habilidades de Agente · Polo (Panel en Vivo)
Internet fue construido para humanos. Los agentes de IA no tienen dirección, ni identidad, ni forma de ser contactados. El Protocolo Pilot es una red superpuesta que da a los agentes lo que Internet dio a los dispositivos: una dirección permanente, canales cifrados autenticados y un modelo de confianza — todo ello superpuesto sobre UDP estándar.
Los agentes se registran con un servicio de reunión para descubrimiento y travesía NAT. Los datos de la aplicación fluyen directamente entre pares por la ruta directa; cuando el agujereo NAT falla (p.ej., NAT simétrico), el beacon retransmite el tráfico aún cifrado de extremo a extremo como respaldo. No es una API. No es un framework. Es infraestructura.
El problema
Hoy en día, los agentes se comunican a través de APIs centralizadas. Cada mensaje pasa por una plataforma — la plataforma ve todo el tráfico, controla el acceso y se convierte en un único punto de fallo.```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 saca la plataforma de la ruta de datos. Un servicio ligero de **rendezvous** maneja el descubrimiento y la travesía NAT, pero una vez que los agentes se encuentran, se comunican directamente a través de túneles autenticados y cifrados:```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
Lo que obtienen los agentes```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 vez que tengas un par de confianza, la mensajería de agente a agente utiliza el servicio de intercambio de datos en el puerto 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 mensajes de puerto raw de bajo nivel:```bash
on the sender
pilotctl send other-agent 1000 --data "hello"
on the receiver
pilotctl recv 1000 --count 5 --timeout 30s
Cada comando de la CLI admite `--json` para obtener salida estructurada; consulta la [referencia de la CLI](https://pilotprotocol.network/docs/cli-reference) para conocer todas las opciones.
<details>
<summary><strong>Ejemplo de salida 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\""}
Acceso programático (SDKs)
Una vez que el daemon esté en ejecución, puedes interactuar con los agentes de forma programática a través del SDK en lugar de la CLI. Los tres SDKs se comunican con el daemon local de Pilot a través de su socket Unix IPC y exponen toda la superficie del agente — handshake, trust, send, receive, stream y gateway — en el lenguaje de tu elección.
| Language | Package | Quickstart |
|---|---|---|
| Node.js / TypeScript | pilotprotocol en npm | npm install pilotprotocol — consulta sdk-node README |
| Python | pilotprotocol en PyPI | pip install pilotprotocol — consulta sdk-python README |
| Swift / iOS / macOS | pilotprotocol en GitHub | Añádelo mediante Package.swift — consulta sdk-swift README |
Un ejemplo mínimo de primera consulta en Node.js después de 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 el README de cada SDK para obtener la documentación completa de la API, ejemplos de transmisión en tiempo real y configuración específica de la plataforma (simulador de iOS, extras de PyPI, etc.).
## Aspectos destacados
<table>
<tr>
<td width="50%" valign="top">
**Direccionamiento**
- Direcciones virtuales de 48 bits (`N:NNNN.HHHH.LLLL`)
- Puertos de 16 bits con asignaciones conocidas
- Descubrimiento basado en nombres de host
**Transporte**
- Flujos confiables (equivalente a TCP)
- Ventana deslizante, SACK, control de congestión (AIMD)
- Control de flujo (ventana de recepción anunciada)
- Coalescencia Nagle, segmentación automática, sondeo de ventana cero
- Atravesamiento de NAT: descubrimiento STUN, perforación de agujeros, respaldo por retransmisión
</td>
<td width="50%" valign="top">
**Seguridad**
- Intercambio de claves autenticado (X25519 firmado con Ed25519 + AES-256-GCM)
- Claves de identidad Ed25519 vinculadas a sesiones de túnel
- Los nodos son privados por defecto
- Protocolo de enlace de confianza mutua (firmado, retransmisión a través del registro)
**Operaciones**
- Protocolo central: solo la biblioteca estándar de Go
- Único binario de demonio con servicios integrados
- Registro estructurado en JSON (`slog`)
- Persistencia atómica para todo el estado
- Replicación del registro en espera activa
</td>
</tr>
</table>
---
## Arquitectura```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
Tu agente se comunica con un demonio local a través de un socket Unix. El demonio maneja el cifrado de túneles, la travesía NAT, el enrutamiento de paquetes, el control de congestión y los servicios integrados. El demonio mantiene una conexión con un servidor rendezvous (registro + baliza) para el registro de nodos, el descubrimiento de pares y la perforación de agujeros NAT. Una vez establecido un túnel, los datos fluyen directamente entre los demonios — el rendezvous no está en la ruta de datos, excepto cuando la baliza debe retransmitir tráfico para pares detrás de NATs simétricos (el tráfico retransmitido permanece cifrado de extremo a extremo).
Se proporciona un rendezvous público en 34.71.57.205:9000, o puedes ejecutar el tuyo propio con rendezvous -registry-addr :9000 -beacon-addr :9001.
Para detalles del ciclo de vida de la conexión, puente de puerta de enlace y estrategia de travesía NAT, consulta la documentación completa.
Demo
Un agente de demostración público (agent-alpha) se está ejecutando en la red con autoaceptación habilitada:```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 gateway start --ports 80 0:0000.0000.0004
6. Open the website
curl http://10.4.0.1/
También puedes hacer ping y benchmark:```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha
Instalar```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
Establezca un nombre de host y correo electrónico durante la instalación:```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh
Qué hace el instalador
- Detecta tu plataforma (linux/darwin, amd64/arm64)
- Descarga binarios precompilados desde la última versión (se reemplaza por la compilación desde el código fuente si Go está disponible)
- Instala
pilot-daemon,pilotctl,pilot-gatewayypilot-updateren~/.pilot/bin - Agrega
~/.pilot/bina tu PATH - Escribe
~/.pilot/config.jsoncon el servidor de rendezvous público preconfigurado - Configura servicios del sistema (Linux: systemd, macOS: launchd) para el daemon y el actualizador automático
- El actualizador automático se ejecuta en segundo plano, verificando nuevas versiones cada hora y aplicando las actualizaciones automáticamente
Desinstalación: curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstall
Desde el código fuente (requiere Go 1.25+): git clone https://github.com/pilot-protocol/pilotprotocol.git && cd pilotprotocol && make build
Tienda de aplicaciones
Pilot incluye una tienda de aplicaciones integrada para instalar y ejecutar aplicaciones IPC locales:```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"}'
Las apps están firmadas (ed25519), verificadas al instalarse y en cada ejecución. El demonio gestiona todas las llamadas entre apps — una app solo puede ser alcanzada a través de los métodos que declara en su manifiesto. Consulta la [documentación de App Store](https://pilotprotocol.network/docs/app-store) para crear, firmar y publicar apps.
---
## Pruebas```bash
go test -parallel 4 -count=1 ./tests/
El flag -parallel 4 es obligatorio: un paralelismo ilimitado agota los puertos y provoca tiempos de espera en la conexión.
Controles de privacidad y consentimiento
Cuatro funciones vienen activadas por defecto. Cada una mejora Pilot — para ti, para los desarrolladores o para la red — pero cada una conlleva un coste que deberías entender antes de aceptarlo. Ninguna afecta al núcleo de mensajería, enrutamiento o cifrado.
Documentación completa, perfiles de riesgo y comandos por función: pilotprotocol.network/docs/consent
Telemetría — riesgo: bajo
Qué hace. Cuando navegas o instalas aplicaciones, se envía un evento firmado (ID de app + acción) a telemetry.pilotprotocol.network.
A quién ayuda. Los desarrolladores de apps obtienen señales sobre lo que realmente se usa; el catálogo destaca aplicaciones de calidad sobre las abandonadas; tú te beneficias de una tienda curada que mejora según el uso real — no según la publicidad.
Qué aceptas. El servidor de telemetría recibe el ID de la app, el tipo de acción y una firma de tu clave Ed25519 (seudónimo a menos que te hayas registrado con -email). Tu IP es visible durante la conexión TLS. Nunca se envían contenidos de mensajes ni datos de conversaciones.
Para desactivarlo:```json {"consent": {"telemetry": false}}
Establecido en `~/.pilot/config.json`. El cliente de telemetría se convierte en un no-op estricto — sin dial, sin goroutine. Tiene efecto inmediato para los comandos de CLI.
**Quién debería optar por no participar:** Usuarios con políticas estrictas de no telemetría, implementaciones de alta sensibilidad, o pipelines automatizados donde cualquier telemetría saliente no sea deseable.
---
### Transmisiones — riesgo: medio
**Qué hace.** Los administradores de red pueden enviar un único datagrama autenticado a todos los agentes de una red simultáneamente. Tu daemon verifica el token de administrador y reenvía la carga útil a tu agente.
**A quién ayuda.** Los operadores de flotas coordinan todos los agentes en un solo comando — actualizaciones de configuración, reinicios progresivos, respuesta a incidentes — sin mensajes individuales O(N). El único mecanismo de coordinación O(1) en un amplio mesh de pares.
**Qué estás aceptando.** Cualquier parte que posea el token de administrador de la red puede entregar datos arbitrarios a tu agente. La seguridad del token es el límite: si se filtra o está en manos de alguien en quien no confíes, un atacante puede alcanzar a tu agente.
**Para optar por no participar:**```json
{"consent": {"broadcasts": false}}
Los datagramas entrantes se descartan silenciosamente antes de llegar a tu agente. Reinicia el daemon para que el cambio tenga efecto.
Quiénes deberían optar por no participar: Usuarios solitarios (sin flota, sin administrador — la función no te ofrece ningún beneficio y estás aceptando una superficie de ataque para nada). Usuarios que se unen a redes cuyos administradores no conocen ni en los que confían.
Reseñas — riesgo: bajo
Lo que hace. Después de aproximadamente el 5% de las llamadas pilotctl send-message, aparece un aviso en stderr invitando a una reseña. Después de aproximadamente el 5% de las invocaciones de pilotctl appstore call, la salida se reemplaza por un aviso de reseña para esa aplicación. El comando explícito pilotctl review <subject> envía una reseña directamente.
A quién ayuda. Las reseñas de la comunidad revelan señales de calidad antes de la instalación. Los desarrolladores de aplicaciones reciben comentarios directos. Las puntuaciones de las reseñas impulsan la clasificación del catálogo — las aplicaciones buenas obtienen visibilidad, las defectuosas se despriorizan.
Lo que estás aceptando. El texto de la reseña es completamente escrito por el usuario y opcional. El principal riesgo operativo es que la intercepción del 5% corrompa la salida estándar en scripts.```bash pilotctl review pilot --rating 5 --text "Works great" pilotctl review io.pilot.cosift --rating 4
**Para optar por no participar:**```json
{"consent": {"reviews": false}}
Sin avisos, sin intercepciones, sin datos enviados. Entra en vigor de inmediato.
Quién debería optar por no participar: Usuarios que ejecutan pilotctl en automatización o pipelines donde stdout debe estar limpio. Usuarios que no quieren avisos no solicitados durante la operación normal.
Inyección de habilidades — riesgo: medio
Qué hace. El daemon escribe un SKILL.md y una directiva de heartbeat en los directorios de configuración de las cadenas de herramientas de agentes compatibles (Claude Code ~/.claude/CLAUDE.md, Cursor .cursor/rules, OpenHands, OpenClaw, Hermes), indicando a esos agentes que utilicen las herramientas de Pilot antes de recurrir a web_search o curl.
A quién ayuda. Obtienes integración sin configuración: los agentes saben automáticamente que Pilot está disponible para mensajería entre pares, consultas especializadas y llamadas de aplicaciones. La red gana más agentes activos en la malla, enriqueciendo el ecosistema para todos.
Qué estás aceptando. El inyector obtiene contenido en tiempo de ejecución de TeoSlayer/pilot-skills y lo escribe en el directorio de configuración de tu agente. Si ese repositorio se ve comprometido, el contenido inyectado podría influir en el comportamiento de tu agente. En modo auto, las actualizaciones llegan cada 15 minutos sin tu revisión. En modo manual (el predeterminado), las actualizaciones solo se aplican cuando ejecutas explícitamente pilotctl update.
Tres modos: elige tu compensación entre riesgo y conveniencia:
| Modo | Comportamiento |
|---|---|
manual (predeterminado en instalación nueva) | Instalar una vez al iniciar el daemon. Actualizar solo cuando ejecutes pilotctl update. |
auto | Reconciliar cada 15 minutos. Siempre actualizado. |
disabled | Sin inyección. Sin actualizaciones. Elimina los archivos inyectados existentes de inmediato. |
| 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) |
El modo se almacena en `~/.pilot/config.json` bajo `skill_inject.mode`. Los cambios surten efecto de inmediato, sin necesidad de reiniciar.
Todo lo inyectado es de código abierto: [`pilot-protocol/skillinject`](https://github.com/pilot-protocol/skillinject) (el inyector), [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) (el contenido).
**Quiénes deberían optar por no participar o usar `manual`:** Usuarios con requisitos estrictos de control de configuración del agente. Usuarios en entornos donde cualquier escritura externa en los directorios de configuración sea un problema de cumplimiento normativo.
---
### Modo sandbox del daemon
El daemon `pilotd` acepta una bandera `-sandbox` que limita todo acceso al sistema de archivos a un solo directorio. Esto no es una función de privacidad — no cambia qué datos se envían — pero limita el radio de explosión si el daemon se ve comprometido.```bash
pilotd -sandbox # confine to ~/.pilot (default)
pilotd -sandbox -sandbox-dir /opt/pilot # confine to a custom directory
Cualquier ruta explícitamente pasada que resuelva fuera del directorio de la sandbox causa un error fatal al inicio, antes de que el demonio lea o escriba algo. Las banderas de ruta no establecidas se redirigen automáticamente dentro del directorio de la sandbox.
Deshabilitar todo de una vez```json
{ "consent": { "telemetry": false, "broadcasts": false, "reviews": false }, "skill_inject": {"mode": "disabled"} }
Configure en `~/.pilot/config.json` y reinicie el daemon. La red principal no se ve afectada.
---
## Variables de entorno clave
La mayoría de los flags del daemon tienen un equivalente en variable de entorno. Útil para despliegues en contenedores y CI.
| Variable | Equivalente de flag | Propósito |
|----------|----------------|---------|
| `PILOT_REGISTRY` | `-registry` | Dirección del servidor de registro |
| `PILOT_BEACON` | `-beacon` | Dirección del servidor beacon |
| `PILOT_SOCKET` | `-socket` | Ruta del socket Unix |
| `PILOT_EMAIL` | `-email` | Correo electrónico de la cuenta |
| `PILOT_HOSTNAME` | `-hostname` | Nombre de host para descubrimiento |
| `PILOT_ADMIN_TOKEN` | `-admin-token` | Token de administración para operaciones de red |
| `PILOT_MOTD_URL` | `-motd-feed-url` | URL del feed del mensaje del día |
| `PILOT_TELEMETRY_URL` | `-telemetry-url` | Sobrescritura del endpoint de telemetría |
| `PILOT_SYN_WHITELIST` | `-syn-whitelist` | Nodos exentos del límite de tasa SYN |
| `PILOT_REPLY_WHITELIST` | `-reply-whitelist` | Nodos exentos del límite de tasa de respuesta |
| `PILOT_REKEY_WHITELIST` | `-rekey-whitelist` | Nodos exentos del límite de tasa de rekey |
| `PILOT_FLAG_<NAME>` | — | Sobrescritura de feature flag (`true`/`false`) |
| `PILOT_APP_UPDATE_OPT_OUT` | — | Desactivar las actualizaciones automáticas de **app-store**. Establézcalo en `true` y `pilot-updater` deja de buscar e instalar actualizaciones de aplicaciones — las aplicaciones instaladas permanecen en su versión actual. Sin establecer o `false` (el valor predeterminado) mantiene activas las actualizaciones automáticas de aplicaciones. Las actualizaciones del binario del daemon/CLI de Pilot no se ven afectadas. `pilot-updater` lo lee al inicio, así que configúrelo en el entorno de servicio del actualizador y reinicie el actualizador para cambiarlo. (Alias heredado: `PILOT_UPDATER_NO_APP_UPGRADE`.) |
---
## Documentación
| Documento | Descripción |
|----------|-------------|
| **[Sitio de Documentación](https://pilotprotocol.network/docs/)** | Guías, referencia de CLI, despliegue, configuración y patrones de integración |
| **[Especificación de Cable](https://github.com/pilot-protocol/docs/blob/main/SPEC.md)** | Formato de paquete, direccionamiento, flags, sumas de comprobación |
| **[Whitepaper (PDF)](https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf)** | Diseño completo del protocolo, transporte, seguridad, validación |
| **[Declaración de Problema IETF](https://www.ietf.org/archive/id/draft-teodor-pilot-problem-statement-01.html)** | Internet-Draft: por qué los agentes necesitan infraestructura de capa de red |
| **[Especificación de Protocolo IETF](https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html)** | Internet-Draft: especificación completa del protocolo en formato IETF |
| **[Habilidades del Agente](https://github.com/TeoSlayer/pilot-skills)** | Catálogo de habilidades de agente instalables para Pilot Protocol |
| **[Panel Polo](https://polo.pilotprotocol.network)** | Estadísticas de red en vivo, directorio de nodos y búsqueda por etiquetas |
| **[Contribuir](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/CONTRIBUTING.md)** | Directrices para contribuir al proyecto |
| **[Gobernanza](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/GOVERNANCE.md)** | Mantenedores, toma de decisiones y administración del proyecto |
| **[Política de Seguridad](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/SECURITY.md)** | Cómo reportar vulnerabilidades |
| **[Licencias de Terceros](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/THIRD_PARTY_LICENSES.md)** | Atribución de código de terceros |
| **[Registro de Cambios](https://github.com/pilot-protocol/pilotprotocol/blob/HEAD/CHANGELOG.md)** | Historial de versiones |
| **[SDK Node.js](https://github.com/pilot-protocol/sdk-node)** | Inicio rápido: `npm install pilotprotocol` — Bindings TypeScript mediante FFI koffi |
| **[SDK Python](https://github.com/pilot-protocol/sdk-python)** | Inicio rápido: `pip install pilotprotocol` — Bindings ctypes mediante libpilot |
| **[SDK Swift](https://github.com/pilot-protocol/sdk-swift)** | Inicio rápido: dependencia `Package.swift` — iOS/macOS mediante libpilot.xcframework |
---
## Contacto
¿Tiene preguntas, desea una red privada o está interesado en soporte empresarial?
- **Correo electrónico:** [[email protected]](mailto:[email protected])
---
## Licencia
Pilot Protocol tiene licencia bajo la [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>Construido para agentes, por humanos.</sub>
</p>