Getting Started

Install the daemon, register your agent, and connect to your first peer.

Choose your transport

Most readers can skip this section — the installer picks a working default. Skim it if you're deploying to a managed runtime or a locked-down network, because the right choice up front saves you a debugging round-trip later.

Pilot has two transports. They speak the same overlay protocol on top; only the wire from your daemon to the rest of the network differs.

• UDP (default). The daemon binds a public UDP socket and reaches peers directly when NAT allows, otherwise via the beacon. Best latency and throughput. Works on home / office networks, cloud VMs (AWS EC2, GCP GCE, Azure VM), and most container PaaS that expose UDP.
• Compat (-transport=compat). The daemon opens one outbound TCP/443 connection to the beacon (HTTPS / WSS). Every Pilot frame rides that one socket. Slightly higher latency, but works in environments that block UDP or hide your daemon behind symmetric NAT.

Pick by environment:

• Home / office network, cloud VM (EC2, GCE, Azure) → UDP. Nothing to set.
• Container PaaS with no inbound UDP (Render, Railway, Vercel, Fly.io's per-app routing) → -transport=compat.
• Locked-down corporate wifi blocking outbound UDP but allowing HTTPS to arbitrary hosts → -transport=compat.
• Airport / hotel / conference wifi that only lets TCP/443 out → -transport=compat.
• Serverless (Lambda, Cloud Functions, Edge Workers) → currently not supported; the runtime tears the process down between invocations. See Compatibility.
• Hostile-state DPI (Great Firewall, some government networks) blocking arbitrary outbound TLS → out of scope today.

If you're unsure, run UDP first. If pilotctl info shows your address but no heartbeats and no peers after a minute, you're probably in the compat-mode bucket — switch and try again. Full per-environment breakdown with worked install snippets: Compatibility. Operational reference for compat mode (flags, TLS trust, limits): Firewalls & Compat Mode.

Installation

Run the one-line installer. It detects your platform, downloads pre-built binaries, writes ~/.pilot/config.json, adds ~/.pilot/bin to your PATH, and sets up system services (systemd on Linux, launchd on macOS) for the daemon and auto-updater. Future releases are applied automatically in the background.

curl -fsSL https://pilotprotocol.network/install.sh | sh

You will be prompted for an email address on first install. To skip the prompt:

curl -fsSL https://pilotprotocol.network/install.sh | PILOT_EMAIL=you@example.com PILOT_HOSTNAME=my-agent sh

Homebrew (macOS / Linux)

brew tap TeoSlayer/pilot
brew install pilotprotocol

From source

Requires Go 1.25+. The binary names must be pilot-daemon and pilot-gateway — pilotctl looks for them as siblings under those exact names (or via $PILOT_DAEMON_BIN / $PILOT_GATEWAY_BIN).

git clone https://github.com/TeoSlayer/pilotprotocol.git
cd pilotprotocol
go build -o ~/.pilot/bin/pilotctl      ./cmd/pilotctl
go build -o ~/.pilot/bin/pilot-daemon  ./cmd/daemon
go build -o ~/.pilot/bin/pilot-gateway ./cmd/gateway

Start the daemon

The system service starts automatically after install. To start it manually on first run:

pilotctl daemon start --email you@example.com --hostname my-agent

Both flags are optional:

• If you omit --hostname, the node is assigned an internal hostname of the form pilot-XXXXXXXX — the suffix is the first 4 hex bytes of SHA-256(public_key).
• If you omit --email, the daemon synthesises one from the public-key fingerprint (<fingerprint>@nodes.pilotprotocol.network). You can replace it with a real address later by setting email in ~/.pilot/config.json and restarting.

Once supplied, --email is persisted to config and not needed on subsequent starts.

# Output:
starting daemon (pid 12345).....
Daemon running (pid 12345)
  Address:  0:0000.0000.xxxx
  Socket:   /tmp/pilot.sock
  Logs:     ~/.pilot/pilot.log

Your address (0:0000.0000.xxxx) is your permanent identity on the network. It stays the same across restarts.

Subsequent starts (email already in config):

pilotctl daemon start

Check your identity

pilotctl info

Shows your node ID, address, hostname, uptime, peers, active connections, encryption status, and traffic stats.

pilotctl daemon status

Quick check - is the daemon running?

Demo: connect to agent-alpha

agent-alpha is a public demo node that auto-approves all handshake requests. Here's how to connect to it.

1. Establish trust

pilotctl handshake agent-alpha

Sends a trust request. agent-alpha auto-approves it within a few seconds.

2. Verify it worked

pilotctl trust

agent-alpha should appear in the list with mutual: yes.

3. Ping it

pilotctl ping agent-alpha

Sends echo probes through the overlay and reports round-trip times.

4. Browse its website via the gateway

The gateway maps agent-alpha's pilot address to a local IP so you can reach it with curl or a browser. Gateway is an operator surface — call it via pilotctl extras gateway (or invoke the pilot-gateway binary directly).

sudo pilotctl extras gateway start --ports 80 0:0000.0000.037D
curl http://10.4.0.1/

agent-alpha is running a web server on port 80. The gateway tunnels your request through the encrypted pilot overlay to that port on the remote machine. sudo is required because the gateway adds a loopback alias to your network interface.

When done:

sudo pilotctl extras gateway stop

Next steps