Flow

Gateway

Reach a service on a remote pilot node using curl, a browser, or any TCP client. Ports are not translated — the port you connect to locally must match the port the remote service is listening on.

How it works

The gateway lets you connect to a TCP service running on a remote pilot node using normal tools — curl, a browser, netcat, anything.

When you start the gateway with a pilot address, it:

1. Picks a local IP from a private subnet (default 10.4.0.0/16) and adds it as a loopback alias on your network interface
2. Starts TCP listeners on that IP for every port you specify
3. When a connection comes in, tunnels it through the encrypted pilot overlay to the remote machine

On the remote side, the incoming pilot connection arrives at the same port number. So if you start the gateway on port 8080, the remote machine needs a service actually listening on port 8080 — the gateway does not translate ports.

sudo is always required. Adding the loopback alias requires root on both macOS and Linux, regardless of which port you use.

Access a remote server

This is the most common use case: a peer is running a server and you want to reach it.

Example: agent-alpha is running a web server on port 80. To browse it:

# 1. Trust the peer first (required)
pilotctl handshake agent-alpha

# 2. Start the gateway — maps 0:0000.0000.037D to 10.4.0.1
sudo pilotctl gateway start --ports 80 0:0000.0000.037D

# 3. Connect using any TCP tool
curl http://10.4.0.1/
# or open http://10.4.0.1/ in a browser

# 4. Stop when done
sudo pilotctl gateway stop

The first pilot address you map gets 10.4.0.1, the second gets 10.4.0.2, and so on.

Multiple peers at once

sudo pilotctl gateway start --ports 80,8080 0:0000.0000.037D 0:0000.0000.0002
# First peer  → http://10.4.0.1/  and  http://10.4.0.1:8080/
# Second peer → http://10.4.0.2/  and  http://10.4.0.2:8080/

Expose your own server on pilotprotocol network

To let a trusted peer reach a service running on your machine, you just run the server — no special gateway setup needed on your side. The peer runs the gateway on their end and connects to you.

Your machine (the server)

# Start your server on whatever port you want
python3 -m http.server 8080
# nginx, caddy, your app — anything that listens on a TCP port

# Find your pilot address to share with the peer
pilotctl info
# Address: 0:0000.0000.xxxx  ← share this

When the peer sends a handshake, approve it:

pilotctl pending            # see incoming requests
pilotctl approve <node_id>

Peer's machine (the client)

# --ports 8080 must match the port your server is actually on
pilotctl handshake 0:0000.0000.xxxx
sudo pilotctl gateway start --ports 8080 0:0000.0000.xxxx
curl http://10.4.0.1:8080/

No port forwarding, no VPN, no firewall changes needed on your side. The pilot overlay handles the traversal.

Manage mappings

List current mappings

pilotctl gateway list

Add a mapping to a running gateway

pilotctl gateway map 0:0000.0000.0007           # auto-assign local IP
pilotctl gateway map 0:0000.0000.0007 10.4.0.5  # assign a specific IP

Remove a mapping

pilotctl gateway unmap 10.4.0.1

Stop the gateway

sudo pilotctl gateway stop

Notes & limits

• Ports are not translated — the port you specify in --ports is the port the remote machine must be listening on. The gateway forwards traffic to the same port number on the other side.
• sudo required — loopback alias creation requires root on macOS and Linux, regardless of port number.
• TCP only — the gateway does not support UDP.
• Trust required — you must have mutual trust with the remote node. Run pilotctl handshake first.
• Default ports — if you omit --ports, the gateway listens on: 7, 80, 443, 1000, 1001, 1002, 8080, 8443.
• Cleanup — loopback aliases are removed automatically on gateway stop or gateway unmap.

Scriptorium: ready intelligence feeds

Scriptorium is a service hosted on Pilot Protocol that delivers continuously updated intelligence briefs — market data, prediction markets, and more — directly to your agents. No public internet exposure, no anonymous callers. Trust is established through the normal pilot handshake.

1. Start the gateway

sudo pilotctl gateway start --ports 8100 0:0000.0000.3814

2. Query endpoints

Prediction markets — today:

curl "http://10.4.0.1:8100/summaries/polymarket?from=2026-04-02T00:00:00Z"

Prediction markets — specific window:

curl "http://10.4.0.1:8100/summaries/polymarket?from=2026-04-01T00:00:00Z&to=2026-04-02T00:00:00Z"

Stock market — date shorthand:

curl "http://10.4.0.1:8100/summaries/stockmarket?from=2026-04-02"