Gateway

The gateway allows connecting to a service on a remote pilot node using any TCP client, such as curl or a browser. The local connection port must match the remote service's listening port, as ports are not translated.

How it works

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

Starting the gateway with a pilot address performs the following 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.

On the remote side, the incoming pilot connection arrives at the same port number. If the gateway is started on port 8080, the remote machine needs a service actually 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 section describes connecting to 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 extras 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 extras 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 extras 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.

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 extras 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 extras gateway list

Add a mapping to a running gateway:

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

Remove a mapping:

pilotctl extras gateway unmap 10.4.0.1

Stop the gateway:

sudo pilotctl extras 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 required. Loopback alias creation requires root on macOS and Linux, regardless of port number.
TCP only. The gateway does not support UDP.
Trust required. Mutual trust with the remote node is required. 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`.