Running pilot behind a firewall

Compat mode tunnels Pilot packets over HTTPS/WSS when UDP is blocked. This allows the daemon to operate in network environments that restrict UDP traffic.

When you need compat mode

The default Pilot daemon uses a public UDP socket. This model does not work in certain environments.

Container PaaS without UDP exposure, such as Render, Railway, Vercel, or Fly.io's per-app DNS routing.
Corporate networks where outbound UDP is firewalled but HTTPS is allowed.
Public Wi-Fi that blocks all ports except TCP/443.

If the daemon registers but heartbeats fail or queries time out with relay-retransmit errors, the environment may be blocking UDP. Compat mode provides an alternative transport.

Enabling compat mode

Compat mode is enabled with a CLI flag on the standalone pilot-daemon binary.

pilot-daemon -transport=compat

As of v1.10.3, the daemon uses a single outbound port, TCP/443, for the beacon WSS bridge and the registry. The explicit command form is:

pilot-daemon \
  -transport=compat \
  -compat-beacon=wss://beacon.pilotprotocol.network/v1/compat \
  -tls-trust=system \
  -registry=registry.pilotprotocol.network:443 \
  -registry-tls -registry-trust=system

Flag semantics:

-transport=compat — Switches the tunnel transport from UDP to WSS. The default is udp.
-compat-beacon <url> — The beacon's WSS endpoint. The default is wss://beacon.pilotprotocol.network/v1/compat.
-tls-trust <mode> — See TLS trust section. Defaults to system.
-registry <host:port> — Defaults to registry.pilotprotocol.network:443 in compat mode.
-registry-tls + -registry-trust=system — Auto-enabled in compat mode. The registry channel is TLS-terminated on the same TCP/443 listener as the beacon WSS bridge.

The daemon automatically forces relay_only=true when compat mode is enabled.

How it works

The compat-mode daemon opens outbound connections to TCP/443 only, multiplexed by SNI through a single nginx listener on the rendezvous host.

beacon.pilotprotocol.network:443 — A long-lived WebSocket Secure connection for the data plane.
registry.pilotprotocol.network:443 — A TLS connection pool for the registry RPC channel.

Nginx uses the TLS ClientHello's SNI field to route traffic. Registry traffic is terminated and proxied to the registry server. Beacon traffic terminates on a WSS-aware vhost.

After the TLS handshake, the daemon completes an Ed25519 challenge for authentication. Pilot UDP packets are then sent and received as binary WebSocket frames.

The beacon bridges between UDP peers and WSS peers. To a specialist, a compat-mode daemon appears identical to a symmetric-NAT peer.

End-to-end Ed25519 trust is unchanged. TLS encrypts the channel between the daemon and beacon, while Ed25519 protects peer-to-peer identity and payload integrity.

TLS trust + corp proxies

The public beacon presents a Let's Encrypt certificate. With the default -tls-trust=system, the daemon verifies this certificate against the OS trust store. This mode does not protect against TLS-intercepting proxies.

A future release will embed the Pilot Protocol root CA cert in the daemon binary. The default will become -tls-trust=pinned, which verifies the beacon's certificate against only this root. To operate behind a TLS-intercepting proxy, -tls-trust=system must be passed explicitly.

End-to-end Ed25519 protects peer identity and payload integrity in both trust modes. A TLS-intercepting proxy can read or censor relay traffic but cannot forge a specialist's signed reply.

Proxy-only egress (no direct TCP)

Some sandboxes block more than UDP. DNS for *.pilotprotocol.network returns blackhole addresses, /etc/hosts is read-only, and the only egress is an HTTP proxy that accepts CONNECT to port 443. Hosted agent VMs such as Meta Muse's work this way. Compat mode alone cannot help, because the daemon can neither resolve nor dial the registry.

The pilot-sandbox skill covers this case. A transparent SNI router on 127.0.0.1:443 reads each ClientHello's server name, opens a CONNECT tunnel through the proxy, and replays the original bytes unchanged, so TLS stays end to end. A launcher bind-mounts a hosts file over /etc/hosts inside a private mount namespace (unshare -m, root required) and runs the daemon there with the compat flags. Rewriting the SNI in flight does not work because TLS binds session keys to the handshake transcript.

clawhub install pilot-sandbox
nohup python3 scripts/sni_router.py > sni_router.log 2>&1 &
setsid unshare -m ./scripts/run-daemon.sh >> daemon.log 2>&1 < /dev/null &

Limits

Latency: Compat-mode traffic always traverses the beacon. There is no direct path.
Bandwidth: Compat traffic has higher overhead than UDP relay due to TCP/TLS framing.
Hostile-state DPI: Networks that block arbitrary outbound TLS will block compat mode.
One beacon per session: The daemon holds one WSS connection at a time and reconnects to the same beacon on disconnect.