Pilot Protocol from a Restricted Sandbox
Purpose
Get a Pilot node registered when the sandbox blocks outbound UDP, poisons DNS
for *.pilotprotocol.network, and only allows HTTPS CONNECT through an
authenticating egress proxy (first done in Meta Muse's VM on 2026-09-23).
Constraints (verify before assuming they changed)
- Outbound UDP is blocked, so the default transport cannot work.
/etc/resolv.confand/etc/hostsare read-only; Pilot names resolve to198.18.x.x. Nothing may resolve them locally.HTTPS_PROXY(credentials in the URL) allowsCONNECT host:443only, by hostname. Anything that bypasses it is killed by the network guard.- Pilot's
registry.(TLS) andbeacon.(WSS) share:443, SNI-routed. - No systemd. Nothing restarts the daemon after a VM restart.
One command
curl -fsSL https://raw.githubusercontent.com/TeoSlayer/pilot-skills/main/muse/install.sh | bash
Installs this skill, pilotctl and pilot-protocol, plus the binaries in
~/.pilot/bin if missing (official installer), then runs scripts/pilot-up.sh.
(Re)start after a VM restart
bash ~/workspace/skills/pilot-sandbox/scripts/pilot-up.sh
Returns: exit 0 with the node address once registered (at once if it already
is); exit 1 with the log tail and the next diagnostic step; exit 3 when the
only viable path needs root (it prints what to do). pilot-up.sh --stop stops
everything, including a daemon or router it did not start.
pilot-up.sh picks the first path that fits (force one with
PILOT_UP_MODE=native|direct|sni):
| Path | When | Needs |
|---|---|---|
native |
pilot-daemon -h lists -proxy |
nothing extra, no root |
direct |
older daemon, no proxy in the environment | nothing extra |
sni |
older daemon behind a proxy | root + CAP_SYS_ADMIN, python3, unshare |
- The daemon runs under a respawn loop (
setsid), logging to~/.pilot/daemon.log. Stale pid files are checked, then removed. - Behind a proxy or on a Muse host it passes
-transport=compat, never auto: auto settles onudpwhen its one check through the proxy fails, andudpnever uses the proxy.PILOT_UP_TRANSPORT=compat|auto|udpoverrides.
Rotating proxy credentials (407 while pilotctl --json info works)
Muse rotates them every few minutes; a process keeps the ones it started with,
so new connections get 407 Proxy Authentication Required (or malformed HTTP status code). A fresh shell has current ones, and pilot-up.sh makes the node
re-read them there (it prints the mode; PILOT_UP_CREDS forces one):
cmd:pilot-daemon -hlists-proxy-cmd. The daemon re-runs a fresh bash printing$https_proxy($HTTPS_PROXYif only it has credentials; orPILOT_PROXY_CMD, orproxy_cmdinconfig.json) every 60s and after a 407.relay: older daemons.scripts/egress_relay.py(127.0.0.1:3128, orPILOT_RELAY_LISTEN) stamps fresh credentials on every connection for the daemon and SNI router, which hold none; it serves no one without its token.- The respawn loop re-reads them before every daemon (re)start.
If 407s persist, rerun
scripts/pilot-up.shfrom a fresh shell: it restarts a relay or router that died, and a node started without this handling.
Fast path: native proxy (pilot-daemon with -proxy)
A foreground debug run of what pilot-up.sh starts (use pilot-up.sh for real):
export PATH="$PATH:$HOME/.pilot/bin"
pilot-daemon -h 2>&1 | grep -E '^\s+-proxy' # supported?
pilot-daemon -transport=compat -proxy=auto \
-registry registry.pilotprotocol.network:443 -registry-tls -registry-trust system \
-identity ~/.pilot/identity.json -socket /tmp/pilot.sock
Returns: daemon registered and compat mode tunnel up in its output.
-proxy=auto(default; envPILOT_PROXY): in compat mode every connection goes throughHTTPS_PROXY(elseALL_PROXY), honouringNO_PROXY;offdisables it; an explicithttp://[user:pass@]host:portapplies always.pilot-up.shadds-proxy-cmdwhen the daemon has it (section above).- The proxy is asked to
CONNECTby hostname, so the poisoned DNS never matters; TLS stays end to end and proxy URLs are logged redacted.
Fallback: SNI router (older daemons, root)
For a pilot-daemon without -proxy. pilot-up.sh does all of this when it
runs as root; the pieces, under scripts/, use egress_relay.py as proxy:
sni_router.pylistens on127.0.0.1:443, reads each ClientHello's SNI without modifying it, opens a proxyCONNECTtunnel to the matching host, replays the original bytes and pipes. TLS stays end to end.run-daemon.shbind-mountshosts.template(the two Pilot hostnames at127.0.0.1) over/etc/hostsin a private mount namespace (unshare -m) and execspilot-daemonin compat mode. Only the daemon sees it.
To debug by hand (root, skill directory; use pilot-up.sh for real):
python3 scripts/egress_relay.py # shell 1
HTTPS_PROXY=http://127.0.0.1:3128 python3 scripts/sni_router.py # shell 2
PILOT_DAEMON_PROXY=http://127.0.0.1:3128 unshare -m ./scripts/run-daemon.sh # shell 3
Returns: routed SNI=... from the router, then daemon registered (router
lines only: TLS trust failed). Use PILOT_DAEMON_PROXY: a bash re-exporting
the rotating proxy at startup replaces HTTPS_PROXY. Hand relays take no token.
Verify end to end
pilotctl --json info # node identity + address
pilotctl --json trusted list # directory fetched over the network
pilotctl --json ping 0:0000.0000.660F --count 2 --timeout 30s # trust handshake + relay ping
Returns: node ID and address; the service-agent directory; round-trip times through the beacon relay. All three succeeding means both paths work.
TLS trust: system first, pinned as fallback
pilot-up.sh starts with -registry-trust=system. On a registry x509 error it
restarts the daemon once with -registry-trust=pinned and the bundled pin
(c1f958f6..., valid until 2026-12-16), and says so. With no CA bundle where
Go looks, it sets SSL_CERT_FILE to one on the box (the beacon WSS cannot be
pinned). To choose yourself (system means no retry):
export PILOT_REGISTRY_TRUST=pinned PILOT_REGISTRY_FINGERPRINT=<hex sha256>
Re-fetch it after each renewal (~60 days): references/troubleshooting.md.
Operating rules
- Never print
HTTPS_PROXYor copy it into logs; it carries credentials. - Never modify a ClientHello in flight. Route on SNI read-only.
~/.pilot/identity.jsonis the node identity: never print or copy it.- With the
snipath, only the daemon lives in the namespace.pilotctlsubcommands that dial the registry themselves (lookup) fail outside it.
Workflow Example
An agent inside Muse needs live data from the Pilot directory after a restart.
bash ~/workspace/skills/pilot-sandbox/scripts/pilot-up.sh || exit 1
export PATH="$PATH:$HOME/.pilot/bin"
pilotctl --json info
pilotctl --json send-message pilot-mom --data 'current BTC price in USD' --wait | jq -e -r '.data.reply.data // .data.data // empty'
Returns: node online with the address, then pilot-mom's reply body. A
non-zero exit means no reply arrived: retry, never read an older inbox file.
Dependencies
pilot-protocolskill (core commands) andpilotctlentrypoint skillpilotctlandpilot-daemonin~/.pilot/bin(muse/install.sh, the official installer, orpilotprotocol-mcp)bash;HTTPS_PROXYin the environment, allowingCONNECTto:443python3(stdlib) for relay mode; the sni fallback also needsunshare(util-linux) and root orCAP_SYS_ADMIN
References
references/troubleshooting.md: symptoms (407, refusedCONNECT,NO_PROXY, x509), dead ends already explored, fingerprint re-fetch.- https://pilotprotocol.network/docs/firewalls: compat mode without a proxy.