satmux README

The project's README from github.com/Th0rgal/satmux. As one markdown file: README.md.

satmux

TCP multiplexer and 1-RTT HTTP/TLS relay for geostationary (GEO) inflight Wi-Fi (Inmarsat GX, Viasat, Panasonic, SITA). Pure Python 3 stdlib, zero external dependencies.

Measured inflight over Inmarsat GX Ka-band (~620 ms RTT, SITA AS206433 Amsterdam ground station):

  ORIGIN (6× PARALLEL)  RAW CABIN WI-FI (:443)    1-RTT BBR + ZLIB MUX    SPEEDUP
  ────────────────────  ────────────────────────  ──────────────────────  ─────────
  GitHub Repo           ████████████    TIMEOUT  ███░░░░░░░░░    4.66s  FIXED ✓
  GitHub API            ████████████  TCP RESET  ██░░░░░░░░░░    2.66s  FIXED ✓
  Hacker News           ████████████    TIMEOUT  ██░░░░░░░░░░    2.28s  FIXED ✓
  MDN Docs              ████████░░░░     12.01s  ██░░░░░░░░░░    2.30s     5.2×
  Cloudflare            ██░░░░░░░░░░      2.97s  █░░░░░░░░░░░    1.40s     2.1×
  PyPI JSON API         █████░░░░░░░      7.09s  ██░░░░░░░░░░    2.64s     2.7×
  ──────────────────────────────────────────────────────────────────────────────────
  6-Origin Burst:    19.13s (3/6 failed)  →  5.35s (0/6 failed)   [3.6× faster · -76% TTFB]

Problem

Non-Starlink inflight Wi-Fi usually breaks on three things unrelated to raw bandwidth:

  1. Onboard :443 middleboxes and DNS interception. Cabin gateways intercept :53 DNS and run a transparent :443 split-TCP proxy (PEP) whose state table drops connections under load (Connection reset by peer / TLS timeouts on github.com, api.github.com, package registries). Non-443 TCP ports pass through untouched.
  2. Handshake round-trips (~620 ms per GEO hop). Every new origin normally pays multiple satellite round-trips (DNS + TCP + TLS) before transferring payload bytes.
  3. Cubic congestion collapse. Cabin Wi-Fi packet loss causes standard TCP to halve cwnd repeatedly, leaving most of your per-seat token-bucket cap unused.

How it works

Direct (:443):
  laptop ──▶ cabin DNS + :443 PEP ══(3–4 GEO RTTs)══▶ ground ──▶ origin  (frequent TCP resets)

satmux (:8444):
  laptop ══(12 persistent TCP :8444 BBR + zlib pipes)══▶ ground VM ──(2 ms)──▶ origin

Limits

Setup

1. Ground VM

Rent a small Linux VM ($0.01–$0.03/h, Python 3.9+, open TCP port 8444) close to where the satellite downlinks to fiber. Check curl ipinfo.io on raw cabin Wi-Fi first to see the egress country/ASN:

Pause UDP VPNs (Tailscale/WireGuard) inflight—blocked UDP retry traffic competes for cabin airtime.

2. Run

With a coding agent:

Spin up a temporary Ubuntu VM near my current satellite egress IP, start https://github.com/Th0rgal/satmux on port 8444, connect the local 12-carrier client, enable bin/satmux-macos on, and run bin/satmux-bench.

Or manually:

# 1. Laptop: generate PSK
git clone https://github.com/Th0rgal/satmux.git && cd satmux
openssl rand -hex 32 > mux.psk && chmod 600 mux.psk

# 2. Ground VM: start server
scp satmux.py mux.psk root@<SERVER_IP>:/root/
ssh root@<SERVER_IP> 'nohup env SATMUX_PSK=$(cat /root/mux.psk) python3 /root/satmux.py server --port 8444 >/var/log/satmux.log 2>&1 &'

# 3. Laptop: start client + enable macOS / git / gh routing
SATMUX_PSK=$(cat mux.psk) python3 satmux.py client --host <SERVER_IP> --port 8444 --carriers 12 &
./bin/satmux-macos on <SERVER_IP>

Benchmark or run parallel range downloads:

./bin/satmux-bench
./bin/satmux-get https://example.com/archive.tar.gz

3. Teardown after landing

./bin/satmux-macos off

Restores macOS Wi-Fi proxy settings, ~/.gitconfig, gh http_unix_socket, and launchctl env vars, then destroy the temporary VM.

License

MIT

satmux (Th0rgal/satmux)

Searching Database…

1.1K ·GitHub
What is this?satmux is a TCP multiplexer and 1-RTT HTTP/TLS relay that speeds up slow, lossy geostationary inflight Wi-Fi by keeping warm connections open to a server near the ground station.
Is it an app I install, or a server I run?Both: a local client on your Mac listens on 127.0.0.1:1080 (SOCKS5) and 127.0.0.1:8080 (HTTP CONNECT), and it connects to a relay you start on a temporary Ubuntu VM.
How do I get it running?Spin up a temporary Ubuntu VM near your current satellite egress IP, start the server on port 8444, connect the local 12-carrier client, then enable bin/satmux-macos on and run bin/satmux-bench to measure.
Do I need to install anything extra?Just Python 3, since the project is pure stdlib with zero external dependencies. You also need your own Ubuntu VM near the ground station, because the relay runs there.
What do I have to undo afterwards?The teardown restores macOS Wi-Fi proxy settings, ~/.gitconfig, gh's httpunixsocket and launchctl env vars, then destroys the temporary VM. Skipping it could leave your Mac pointed at a proxy that no longer exists.
Is it meant for Starlink too?No: the README targets non-Starlink GEO links such as Inmarsat GX, Viasat, Panasonic and SITA, and its measurements were taken on Inmarsat GX Ka-band.
Does it work on Windows laptops?The README only documents the macOS client (bin/satmux-macos) and an Ubuntu server, and says nothing about Windows.
Does my traffic go through a server I control?Yes: streams run through a Linux VM you start near the satellite ground station, and the teardown step destroys that VM after landing.
Why are GEO flights so slow to load github.com?Cabin gateways intercept DNS and run a :443 split-TCP proxy that drops connections under load. Each ~620 ms satellite round-trip then adds up across DNS, TCP and TLS handshakes.
How does it avoid the cabin's :443 proxy?Its carrier pool runs on port 8444, which passes through untouched. It keeps 12 warm TCP connections to a Linux VM and sends each stream to the least-loaded one.
How does it handle packet loss on cabin Wi-Fi?Standard Cubic halves its window again and again on loss and wastes your per-seat cap. satmux runs warm BBR connections that aim to use more of that token-bucket cap.
Creator
Th0rgal
Size
<0.1 MB
Stars
1.1K
Updated
CommitNov 07
Age
11d
Commits · 90 Days