Pilot Protocol Agent Network Stack
An agent overlay network over UDP: virtual addresses, encrypted tunnels, and mutual trust between peers.
- Source repo
- pilot-protocol/pilotprotocol
- Stars
- ★ 147
- Last updated
- 1d ago
- License
- AGPL-3.0
- Primary language
- Go
- FA score
- 48/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Teams running agents across several machines that want direct peer connections instead of routing every message through a third-party API platform.
- Not a fit if
- Teams that need fully offline operation with no rendezvous traffic
- Users who cannot let the daemon write into Claude Code or Cursor config dirs
- Anyone wanting a ready-made chat bot instead of a local daemon plus Unix socket
- Source review
- 48/100 · Major gaps
What does this agent do, and when should you use it?
Pilot Protocol is an overlay network for AI agents, written in Go with a core that uses only the standard library. Each agent joins through a local pilot-daemon, registers with a rendezvous service (registry :9000 plus beacon :9001), and receives a 48-bit virtual address such as 0:0000.0000.0005, 16-bit ports, and a resolvable hostname. Data travels over AES-256-GCM encrypted UDP tunnels with STUN discovery and hole-punching; when punching fails the beacon relays the still end-to-end-encrypted traffic. Identity is Ed25519, and peers are private by default until a signed mutual handshake completes. A Unix socket exposes the full surface to the pilotctl CLI and to Node.js, Python, and Swift SDKs, and a built-in signed app store distributes IPC apps.
The install script places pilot-daemon, pilotctl, and pilot-updater in ~/.pilot/bin and registers systemd or launchd services. pilotctl daemon start launches the daemon, which registers the node with registry:9000, obtains a virtual address, and opens encrypted UDP tunnels to peers via STUN and beacon-assisted hole-punching, falling back to relay when needed. Tunnels use Ed25519-bound X25519 key exchange with AES-256-GCM and carry reliable streams with sliding windows, SACK, AIMD congestion control, Nagle coalescing, auto segmentation, and zero-window probing. User-facing commands include pilotctl info/set-hostname/find/ping/bench for self-check and peer probing, pilotctl handshake and pilotctl trust for the mutual trust protocol, send-message plus inbox on the port 1001 data exchange service, and send/recv for raw port messaging. Built-in services also cover echo on :7 and the event stream on :1002, while extras gateway maps a remote agent to a local IP. Every command supports --json, and all three SDKs speak to the daemon over Unix socket IPC with the same handshake, send, recv, stream, and gateway calls.
- Teams running agents across several machines that want direct peer connections instead of routing every message through a third-party API platform.
- Agents behind symmetric NAT or home broadband that still need end-to-end encrypted communication, using the beacon relay as fallback.
- Agents inside locked-down containers or hosted sandboxes such as Meta Muse where only an HTTPS proxy is available, using --transport compat over TLS 443 and WSS.
- Operators who need stable, addressable identities and hostname discovery for a fleet, using pilotctl set-hostname and pilotctl find.
- Organizations that want their own control plane, self-hosting rendezvous with rendezvous -registry-addr :9000 -beacon-addr :9001 and hot-standby registry replication.
- Developers distributing tools as signed IPC apps, publishing and invoking declared methods through pilotctl appstore.
How do you install or deploy this agent?
The official installer detects your platform, downloads prebuilt binaries, and falls back to a source build when Go is available.
curl -fsSL https://pilotprotocol.network/install.sh | shYou can set hostname and email during install:
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent shBuilding from source requires Go 1.25+:
git clone https://github.com/pilot-protocol/pilotprotocol.git
cd pilotprotocol && make buildWhen UDP is blocked and only an HTTPS proxy is available, pick compat mode explicitly:
pilotctl daemon start --transport compatSandboxes without a CA bundle can point at one or pin the registry certificate:
SSL_CERT_FILE=/path/to/ca-certificates.crt pilotctl daemon start
pilotctl config --set registry_fingerprint=<sha256 of its certificate>Uninstall:
curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstallHow do you use this agent?
Start the daemon, handshake with the public demo agent, and confirm trust:
pilotctl daemon start --hostname my-agent --email [email protected]
pilotctl handshake agent-alpha "hello"
pilotctl trustInspect your address, claim a hostname, and test connectivity:
pilotctl info
pilotctl set-hostname my-agent
pilotctl find agent-alpha
pilotctl ping agent-alpha
pilotctl bench agent-alphaExchange structured messages through the port 1001 data exchange service:
pilotctl send-message other-agent --data "hello"
pilotctl inbox
pilotctl inbox read <id>Raw port messaging:
pilotctl send other-agent 1000 --data "hello"
pilotctl recv 1000 --count 5 --timeout 30sAdd --json to any command for structured output:
pilotctl --json info
pilotctl --json find other-agentThe Node.js SDK talks to the running daemon over its Unix socket:
import { createPilot, createAgent } from 'pilotprotocol';
const pilot = await createPilot();
const conn = await pilot.handshake('agent-alpha', 'hello');
await conn.trust();
await conn.send(3000, Buffer.from('ping'));
const msgs = await conn.recv(3000, { count: 1, timeout: 10 });
console.log('Received:', msgs[0].data.toString());Give the container an init process so the daemon does not accumulate zombies:
docker run --init ...Turn off the on-by-default telemetry, broadcasts, review prompts, and skill injection, then restart the daemon:
{
"consent": {
"telemetry": false,
"broadcasts": false,
"reviews": false
},
"skill_inject": {"mode": "disabled"}
}What are this agent's strengths and limitations?
- The platform leaves the data path: once tunnels are up, agents talk directly over UDP, and the rendezvous only handles discovery and NAT traversal.
- Clear security model with Ed25519 identity keys bound to sessions, X25519 key exchange, AES-256-GCM, private-by-default nodes, and a signed mutual handshake.
- Documented degradation paths for hostile networks: symmetric NAT relay that stays end-to-end encrypted, compat mode over TLS 443 plus WSS, and HTTPS_PROXY/ALL_PROXY/NO_PROXY support including rotating-credential proxy_cmd.
- Core protocol uses only the Go standard library, with atomic state persistence, hot-standby registry replication, and structured slog logging; the installer wires up systemd/launchd and auto-updates without requiring root.
- Low integration cost across languages: every pilotctl command supports --json, and Node.js, Python, and Swift SDKs share the same daemon API, plus a signed app store.
- Discovery and hole-punching still depend on a rendezvous; the default points at the public 34.71.57.205:9000, so private control means running your own registry and beacon.
- Four features ship on by default, including telemetry, broadcasts, review prompts, and skill injection that fetches remote content at runtime and writes into Claude Code, Cursor, OpenHands, OpenClaw, and Hermes config directories, refreshing every 15 minutes in auto mode.
- Container deployments need an init process (docker run --init, tini, or shareProcessNamespace); the daemon does not reap orphans itself.
- Building from source requires Go 1.25+, and sandboxes without a CA bundle must set SSL_CERT_FILE or pin the registry fingerprint, which the WSS beacon does not support.
- Tests must run with go test -parallel 4 because unlimited parallelism exhausts ports, and the AGPL-3.0 license constrains closed-source integrations.
How does this agent compare with similar options?
The README positions Pilot Protocol against the MCP-style pattern of agents talking through centralized APIs. Its argument is that a platform in the middle sees all traffic, controls access, and becomes a single point of failure, so Pilot moves the platform out of the data path: the rendezvous handles discovery and NAT traversal while data flows directly over encrypted UDP tunnels between virtual addresses and ports.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Pilot Protocol Agent Network Stack This agent | 48 · Major gaps | CLIFree | ★ 147 | 1d ago | Go | — |
| OrgKernel Agent Trust Layer | 66 · Some gaps | Library / SDKFree | ★ 2.7k | 3mo ago | Python | — |
| AI Maestro | 56 · Major gaps | CLIFree + model costs | ★ 816 | today | TypeScript | Codex · Claude Code |
| Jev Guard | 79 · Good | Agent plugin / skillFree + model costs | ★ 63 | 7d ago | JavaScript | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
README states nodes are private by default and require mutual trust handshake, and it discloses four default-on features (telemetry, broadcasts, reviews, skill injection) with risk profiles and opt-outs, giving data_flow_transparency a 2. least_privilege scores 1: install uses curl | sh and the gateway example requires sudo and NET_ADMIN, with no fine-grained least-privilege guidance. user_confirmation scores 1: skill injection defaults to manual but writes into agent config dirs at install, and broadcasts are on by default and can deliver arbitrary data to the agent without per-event confirmation. sensitive_data_handling scores 1: README mentions telemetry sends Ed25519 signatures and IP, but key storage and log redaction are not detailed. dependency_security scores 1: go.mod pulls many pilot-protocol modules and indirect sigstore dependencies, with no dependency audit or vulnerability scanning evidence. external_effects scores 1: the auto-updater checks hourly and applies updates automatically, a significant external effect despite --pin. rollback scores 1: uninstall and --version pinning exist, but no clear rollback or state recovery for failed auto-updates. source_attribution scores 1: README links IETF draft, whitepaper, and skills repo, but no in-repo attribution of code provenance or third-party components.
self_consistency scores 2: README descriptions of architecture, ports, and transport modes (auto/compat/udp) align with go.mod and test scripts, with no obvious contradictions. dependency_availability scores 1: many dependencies are pilot-protocol-owned modules (app-store, beacon, common, etc.) whose availability and version stability cannot be statically confirmed from this repo, and a replace directive points to a specific pseudo-version. failure_messages scores 2: README shows structured JSON errors with code, message, and hint, and test scripts exercise error paths, so failure messaging is clear.
audience_and_scenarios scores 2: README targets agent developers, operators, and constrained sandbox users, covering CLI, SDK, container, and proxy scenarios. capability_boundaries scores 2: it states the core protocol uses only the Go standard library, gateway is an optional extra, and broadcast is WIP, making boundaries clear. trigger_precision scores 1: skill injection auto-reconciles every 15 minutes in auto mode, and review prompts intercept stdout on ~5% of calls, which is imprecise for automation. environment_fit scores 2: it thoroughly covers no-systemd containers, HTTPS proxies, compat mode, and missing CA bundles.
information_architecture scores 2: README is well structured with problem, architecture, install, testing, and privacy sections. install_notes scores 2: install steps, source build, uninstall, proxy, and container notes are provided. naming_stability scores 1: CLI commands and ports are stable, but no versioned naming conventions or deprecation policy are in-repo. examples_and_faq scores 2: CLI, JSON, Node SDK examples and a demo agent flow are included. known_limitations scores 1: README mentions broadcast WIP, -parallel 4 requirement, and symmetric NAT relay, but lacks a consolidated known-limitations list. license scores 2: LICENSE is the full AGPL-3.0 text, matching metadata. versioning_changelog scores 1: SECURITY.md mentions 1.8.x support, but no CHANGELOG or semantic versioning notes are in-repo. maintenance_responsibility scores 1: SECURITY.md gives a contact email and response time, but publisher identity is unverified, leaving maintenance ownership unclear.
output_usability scores 2: CLI supports --json structured output and SDKs provide programmatic access, usable for automation. marginal_value scores 2: it offers addressing, encrypted tunnels, and a trust model for agents, a clear differentiation from centralized APIs. cost_benefit scores 1: telemetry, broadcasts, reviews, and skill injection are on by default, and the auto-updater runs continuously, with insufficient explanation of the trade-off between benefits and operational/privacy costs for ordinary users.
claim_traceability scores 1: README claims 1048 passing tests and AES-256-GCM encryption, but no traceable test reports or benchmark data are in-repo. cross_source_corroboration scores 1: README, SECURITY.md, go.mod, and test scripts are partially consistent, but key security claims lack multi-source corroboration. fact_inference_separation scores 1: documentation mixes factual descriptions with marketing statements (e.g., 'It is not a framework. It is infrastructure.'), without clearly separating verified facts from inference.
- Install uses curl | sh and the gateway example requires sudo and NET_ADMIN, granting broad privileges; review in an isolated environment first.
- Telemetry, broadcasts, reviews, and skill injection are on by default; broadcasts can deliver arbitrary data to the agent and skill injection writes into agent config dirs, so disable as needed.
- The auto-updater checks hourly and applies updates automatically, potentially introducing unreviewed changes; consider --pin or disabling auto-update.
- go.mod depends on many pilot-protocol-owned modules and indirect dependencies whose availability and security cannot be statically confirmed from this repo.
- Publisher identity is unverified, and maintenance responsibility and update paths are unclear; independently assess before production use.