Gateway

Bridge standard IP/TCP traffic to the Pilot Protocol overlay.

What the gateway does

The gateway maps pilot addresses to local IP addresses on a private subnet. It starts TCP proxy listeners on the specified ports, so you can use standard tools — curl, browsers, any TCP client — to reach agents on the overlay network.

When a connection comes in to a mapped local IP, the gateway opens a pilot connection to the corresponding remote agent and bridges the data bidirectionally.

Starting the gateway

# Map one agent, proxy port 80
sudo pilotctl gateway start --ports 80 0:0000.0000.0004

# Map multiple agents, multiple ports
sudo pilotctl gateway start --ports 80,3000,8080 0:0000.0000.0001 0:0000.0000.0002

# Custom subnet
sudo pilotctl gateway start --subnet 10.5.0.0/16 --ports 80 0:0000.0000.0001

Returns: pid, subnet, mappings [{local_ip, pilot_addr}]

The default subnet is 10.4.0.0/16. Each mapped agent gets the next available IP in the subnet (10.4.0.1, 10.4.0.2, etc.).

How it works

1. The gateway adds a loopback alias for each mapped IP (Linux: ip addr add, macOS: ifconfig lo0 alias)
2. It starts TCP listeners on the specified ports for each mapped IP
3. Incoming TCP connections are bridged to pilot connections on the corresponding remote agent

Managing mappings

Add a mapping

pilotctl gateway map 0:0000.0000.0007          # Auto-assign IP
pilotctl gateway map 0:0000.0000.0007 10.4.0.5  # Specific IP

Remove a mapping

pilotctl gateway unmap 10.4.0.1

List all mappings

pilotctl gateway list

Stop the gateway

pilotctl gateway stop

Examples

Browse an agent's website

sudo pilotctl gateway start --ports 80 0:0000.0000.0004
curl http://10.4.0.1/
curl http://10.4.0.1/status

Access an API on a custom port

sudo pilotctl gateway start --ports 3000 0:0000.0000.0001
curl http://10.4.0.1:3000/api/data
# {"status":"ok","protocol":"pilot","port":3000}

Multi-agent dashboard

sudo pilotctl gateway start --ports 80,8080 0:0000.0000.0001 0:0000.0000.0002
# Agent 1: http://10.4.0.1/
# Agent 2: http://10.4.0.2/

Notes

• Root required — ports below 1024 require root/sudo. Ports 1024+ can run without root
• Loopback aliases — the gateway automatically manages loopback aliases; they are cleaned up on gateway stop or gateway unmap
• Trust required — you must have mutual trust with the remote agent before the gateway can bridge traffic
• TCP only — the gateway proxies TCP connections; UDP is not supported through the gateway