# satmux (Th0rgal/satmux)

> 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.

- GitHub: https://github.com/Th0rgal/satmux
- GitHub.Locker page: https://github.locker/Th0rgal/satmux
- Stars: 1.1K
- Language: Python
- License: MIT
- Last push: 2026-11-07

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**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.


---

## README (checked against GitHub 2026-11-18)

Source: https://github.com/Th0rgal/satmux/blob/main/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):

```text
  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

```text
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
```

- **Persistent non-443 carrier pool (`:8444`):** Keeps 12 pre-warmed TCP connections open to a Linux VM near the satellite ground station, bypassing the cabin `:443` proxy and onboard DNS. Streams are scheduled onto the carrier with the lowest recent byte load so idle browser keepalives do not cause head-of-line queueing.
- **0-RTT stream open (`127.0.0.1:1080` SOCKS5 / `127.0.0.1:8080` HTTP CONNECT):** Returns `OK` locally in `<1 ms` and sends `FT_OPEN` + TLS `ClientHello` in the same TCP burst, saving one full satellite RTT while preserving end-to-end TLS from the laptop.
- **1-RTT ground fetch (`127.0.0.1:8081`):** Sends an encrypted (`BLAKE2b-512` stream + `HMAC-SHA256`) request frame over a warm carrier. The ground VM performs DNS, verified TLS 1.3, and HTTP redirects on fiber (`~2–5 ms`) and compresses plaintext responses with `zlib` before crossing the satellite link.
- **`git` and `gh` CLI routing:** Go binaries such as `gh` ignore macOS `scutil` proxies. `satmux` exposes a `0600` local Unix socket (`/tmp/satmux-gh-tls.sock`) wired to `gh`'s `http_unix_socket` that wraps requests in verified end-to-end TLS on the laptop and tunnels them over SOCKS5, fixing already-running coding agents without restarting them.
- **BBR + `MSS 1280`:** Ground-to-cabin sockets enable `TCP_CONGESTION=bbr` and `TCP_MAXSEG=1280`.

## Limits

- **Latency floor (`~580–650 ms`):** Speed-of-light propagation to geostationary orbit (`35,786 km`) does not change; `satmux` removes extra round-trips, not the physical RTT of one hop.
- **Per-seat shaper (`~4–5 Mbps` typical):** Cabin routers police total bandwidth per client lease. Compressible traffic (HTML, JSON, code, APIs) exceeds that rate in effective throughput via `zlib`; already-compressed binaries (`.mp4`, `.zip`) stay bounded by the seat cap (though BBR + parallel `satmux-get` keep throughput near the ceiling).
- **Single paid session:** Uses your authenticated cabin Wi-Fi lease; it does not bypass captive portals.

## 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:

- **Emirates / Middle East & European flights (Inmarsat GX / SITA `AS206433`):** Amsterdam, Frankfurt, or Hetzner EU (downlink lands in the Netherlands).
- **North America:** `us-east` or `us-west`.
- **Asia-Pacific:** Singapore or Tokyo.

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:

```bash
# 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:

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

### 3. Teardown after landing

```bash
./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

