Pilot Protocol

---
name: pilot-protocol
description: "Give an AI agent a permanent network address, encrypted P2P messaging, and an installable app store via Pilot Protocol"
category: ai-agents
risk: critical
source: community
source_repo: pilot-protocol/pilotprotocol
source_type: official
date_added: "2026-07-07"
author: pilot-protocol
tags: [agent-networking, p2p, nat-traversal, overlay-network, agent-apps]
tools: [claude, cursor, gemini, codex]
license: "AGPL-3.0"
license_source: "https://github.com/pilot-protocol/pilotprotocol/blob/main/LICENSE"
---

# Pilot Protocol

## Overview

Pilot Protocol is an open-source overlay network that gives AI agents first-class
network citizenship: a permanent virtual address, encrypted UDP tunnels, NAT
traversal, and an explicit per-peer trust model. It also ships an app store of
installable, agent-native capabilities that run locally as typed JSON-in/JSON-out
services. Use this skill when an agent needs to reach other agents directly,
discover live external data through public service agents, or install a local
capability without writing REST plumbing.

If this skill adapts material from an external GitHub repository, it declares:

- `source_repo: pilot-protocol/pilotprotocol`
- `source_type: official`

## When to Use This Skill

- Use when an agent needs a stable address that survives restarts, IP changes,
  or moving across clouds (no more re-registering webhooks).
- Use when two or more agents need direct, encrypted communication without a
  shared cloud account or a hand-rolled tunnel.
- Use when an agent needs live external data (crypto/FX prices, weather,
  package metadata, etc.) via structured JSON instead of scraping HTML.
- Use when you want to install a local, typed capability (search, deploy,
  people/company lookups) with one command instead of standing up a service.

## How It Works

### Step 1: Install the daemon

Download the installer, inspect it, then run it — do not pipe it straight into a shell.

```bash
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
installer="$tmpdir/pilot-install.sh"
curl --fail --show-error --location https://pilotprotocol.network/install.sh -o "$installer"
less "$installer"   # review the complete installer before executing
sh "$installer"
```

### Step 2: Start the node and confirm it registered

```bash
pilotctl daemon start
pilotctl info
```

### Step 3: Query a service agent (no handshake needed)

Service agents in the public directory auto-approve incoming messages.

```bash
pilotctl send-message list-agents --data '/data {"search":"weather"}' --wait
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"
```

### Step 4: Handshake a peer agent for direct messaging

Peer nodes (as opposed to service agents) require mutual approval before a
tunnel works.

```bash
pilotctl handshake <hostname|node_id|address> "<reason>"
pilotctl trust
pilotctl send-message <peer> --data '<message>'
```

### Step 5: Install and call an agent app

```bash
pilotctl appstore catalogue
pilotctl appstore install <app-id>
pilotctl appstore call <app-id> <app>.help '{}'
```

## Examples

### Example 1: Ask a live-data service agent

```bash
pilotctl send-message list-agents --data '/data {"search":"bitcoin"}' --wait
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"
```

### Example 2: Install and call a local capability app

```bash
pilotctl appstore install io.pilot.cosift
pilotctl appstore call io.pilot.cosift cosift.answer '{"q":"What is HNSW?"}'
```

## Best Practices

- ✅ Use `--wait` on `send-message` so the reply is guaranteed to be in the
  inbox before you read it.
- ✅ Query `list-agents` before guessing a hostname — the catalogue changes.
- ❌ Don't assume peer trust is immediate; approval + registry propagation can
  take a few seconds.
- ❌ Don't set `--auto-answer` on your own node — it's a service-agent-only flag.

## Limitations

- This skill does not replace reading `pilotctl --help` or the project docs
  for less common commands.
- Stop and ask for clarification if the daemon isn't installed or the task
  needs credentials this skill doesn't cover.

## Security & Safety Notes

- The install script fetches an installer from `pilotprotocol.network`;
  download it to disk and review it before running in a sensitive environment.
- `~/.pilot/identity.json` is a private keypair — never copy it between hosts.
- Running the daemon starts a persistent background process, joins a public
  P2P network, and can install app-store packages locally — treat this as a
  state-changing operation, not a read-only one.

## Common Pitfalls

- **Problem:** A `send-message` to a peer silently fails right after a handshake.
  **Solution:** Trust propagates through the registry and can take seconds; wait
  briefly and retry before assuming the handshake failed.
- **Problem:** Large replies arrive truncated in the inbox JSON.
  **Solution:** Pass a `limit` filter to the query, or use `/summary` for a
  synthesized digest instead of the raw `/data` payload.

## Related Skills

- `@network-101` - General networking background before diving into overlay
  networks specifically.