[ Switch to styled version → ]
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.
`pilot-gateway` is a separate binary and does not ship with the standard install. The `pilot-protocol/gateway` repository is published as a Go library. A standalone `pilot-gateway` binary is not currently published.
When a `pilot-gateway` binary is present, `pilotctl extras gateway` locates it by checking these locations in order:
The gateway connects to a TCP service on a remote pilot node using standard tools like curl or a browser.
When the gateway is started with a pilot address, it performs these actions:
On the remote machine, the incoming pilot connection arrives at the same port number. If the gateway is started for port 8080, the remote machine must have a service 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 the port used.
To reach a server running on a peer machine, for example 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
# pilotctl no longer tracks the gateway; stop it directly:
sudo pkill -TERM pilot-gatewayThe first pilot address mapped is assigned 10.4.0.1, the second is assigned 10.4.0.2, and so on.
To connect to 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/To expose a local TCP service to a peer, the gateway must be run on the server side to bridge the pilot port to the local TCP service. The peer then runs their gateway 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 thisWhen the peer sends a handshake, approve it:
pilotctl pending # see incoming requests
pilotctl approve <node_id>On the 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/The pilot overlay handles traversal, so no port forwarding, VPN, or firewall changes are required.
To list current mappings:
pilotctl extras gateway listThis command may print "no mappings" because live mappings are held in the `pilot-gateway` process, not `pilotctl`.
`pilot-gateway` owns its in-memory mapping table. There is no IPC to mutate a running gateway. `pilotctl extras gateway map` executes a transient `pilot-gateway` that registers a mapping and exits. To change the mapping set, restart `pilot-gateway` with the new mappings.
pilotctl extras gateway map 0:0000.0000.0007 # transient: register + exit`pilotctl extras gateway unmap` is not supported. Unmapping is owned by the `pilot-gateway` process. Stop the process to release its mappings.
To stop the gateway:
# pilotctl no longer tracks the gateway; stop it directly:
sudo pkill -TERM pilot-gateway