Getting Started

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

Choose your transport

The installer picks a working default. This section matters mainly for managed runtimes or locked-down networks. Pilot has two transports that speak the same overlay protocol; only the wire from the 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 where UDP is blocked or the daemon is 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 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.
Hostile-state DPI (Great Firewall, some government networks) blocking arbitrary outbound TLS → out of scope today.

If unsure, run UDP first. If pilotctl info shows an address but no heartbeats and no peers after a minute, switch to compat mode and try again. See the Firewalls & Compat Mode reference for flags, TLS trust, and limits.

Installation

Run the one-line installer. It detects the platform, downloads pre-built binaries, writes ~/.pilot/config.json, adds ~/.pilot/bin to 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 | [email protected] 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 [email protected] --hostname my-agent

Both flags are optional:

If --hostname is omitted, 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 --email is omitted, the daemon synthesises one from the public-key fingerprint (<fingerprint>@nodes.pilotprotocol.network). It can be replaced 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

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

Subsequent starts (email already in config):

pilotctl daemon start

Behind a firewall? If the daemon can't reach peers, the network may be blocking UDP. Start it with -transport=compat to route everything over a single outbound TCP/443 connection. See Firewalls & Compat Mode for the full flag set, supported environments, and how the WSS bridge works.

Guided quickstart: run pilotctl quickstart for an interactive walkthrough that detects daemon state and guides through discovery, trust, and a first specialist query. See the CLI Reference quickstart section.

Check your identity

pilotctl info

Shows 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.

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 it can be reached 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 runs a web server on port 80. The gateway tunnels the request through the encrypted pilot overlay to that port on the remote machine. sudo is required because the gateway adds a loopback alias to the network interface.

When done:

sudo pilotctl extras gateway stop