Gateway

The gateway allows TCP clients like curl or a browser to reach a service on a remote pilot node. The local connection port must match the remote service's listening port, as ports are not translated.

How it works

The gateway connects to a TCP service on a remote pilot node using standard tools like curl, a browser, or netcat.

When started with a pilot address, the gateway performs these actions:

Picks a local IP from a private subnet (default 10.4.0.0/16) and adds it as a loopback alias on the network interface.
Starts TCP listeners on that IP for every specified port.
When a connection is received, it is tunneled through the encrypted pilot overlay to the remote machine.

The incoming pilot connection arrives at the same port number on the remote side. If the gateway is started on port 8080, the remote machine must have a service listening on port 8080. The gateway does not translate ports.

`sudo` is required. Adding the loopback alias requires root on both macOS and Linux, regardless of the port used.

Access a remote server

This is for reaching a server running on a peer's machine.

Example: Reach a peer running a web server on port 80.

# 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 mapped 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 allow a trusted peer to reach a service on your machine, run the server. No gateway setup is needed on the server side. The peer runs the gateway on their end to connect.

On the server machine:

# 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>

On the peer's (client) machine:

# --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, VPN, or firewall changes are needed on the server 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 specified 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` is required. Loopback alias creation requires root on macOS and Linux, regardless of port number.
TCP only. The gateway does not support UDP.
Trust is required. There must be mutual trust with the remote node. Run `pilotctl handshake` first.
Default ports. If `--ports` is omitted, 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

Deprecated. The gateway-based Scriptorium workflow is still functional, but using Service Agents is recommended. Service agents live on a dedicated network. Join it with `pilotctl network join 9` and call services directly via `pilotctl scriptorium` commands without managing gateway mappings.

Scriptorium is a service hosted on Pilot Protocol that delivers continuously updated intelligence briefs, such as market data and prediction markets. Trust is established through the 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"

Service Agents