# MasterHttpRelayVPN-RUST

A Rust port of [[masterhttprelayvpn]], the Python tool that fronts HTTPS traffic through a free Google Apps Script deployment to look like normal traffic to `www.google.com`. Same idea, different footprint: single static binary, desktop UI via egui, and an Android APK that actually captures system-wide traffic through VpnService. The upstream Python project was published 2026-04-20 by @masterking32; this Rust port by @therealaleph appeared 2026-04-21 and has been iterating daily since.

The main reason to care about the rewrite: the Python client needs a Python runtime, certificates generated at first run, and a handful of pip dependencies that Iranian and Russian users often can't resolve through blocked package mirrors. The Rust binary is a 5-10 MB static executable with no runtime dependencies, runs on routers with 32-bit MIPS, and ships an Android build that most users can side-load without a VPS or rooted phone.

## How it works

Same four-part architecture as the Python original (see [[masterhttprelayvpn]] for the full picture), with some implementation differences worth noting:

1. **Local proxy.** `tokio` + `rustls`. HTTP/CONNECT on `127.0.0.1:8085`, SOCKS5 on `127.0.0.1:8086` (the Python version uses 1080 for SOCKS5 — note the port shift if you're switching).
2. **MITM layer.** `rcgen` generates the local root CA on first run. `cert_installer.rs` pushes it into the OS trust store per platform (Keychain on macOS, certutil on Linux, CertMgr on Windows, manual on Android). The CA sits in the user's data directory — `~/.local/share/mhrv-rs` on Linux, `~/Library/Application Support/mhrv-rs` on macOS.
3. **Fronting transport.** `tokio-rustls` opens TLS to a Google edge IP (default `216.239.38.120`, configurable) with SNI `www.google.com`. Inside, `h2` multiplexes HTTP/2 streams to `script.google.com/macros/s/<DEPLOYMENT_ID>/exec`. The body is JSON describing the real request — URL, headers, method, payload. The `auth_key` config value goes in as a shared secret the Apps Script checks.
4. **Relay.** Apps Script runs `UrlFetchApp.fetch()` on the target, returns the body. Same `Code.gs` as upstream.

The outer SNI is Google, the inner Host is `script.google.com` — both Google-owned, so this isn't classic [[domain-fronting]] (no high-reputation decoy hiding an unrelated backend). It's Google routing traffic based on the inner Host between its own properties. See [[serverless-relay-transport]] for why this particular trick still works when most CDN fronting doesn't.

## The hybrid routing trick

The detail that makes the free Apps Script quota actually last: Google-owned destinations skip the Apps Script detour entirely.

When the client sees a request for `youtube.com`, `gmail.com`, or any other Google property, it tunnels directly through the Google edge with SNI rewriting — the outer SNI stays `www.google.com` (so the censor sees nothing new), but there's no Apps Script invocation, no `UrlFetchApp.fetch()`, no quota burn. Only non-Google destinations pay the Apps Script cost. For users who spend most of their time on Google services (which describes a lot of the target population — YouTube, Gmail, Google Docs, Android Play Services), the 20,000-calls-per-day free quota is rarely the bottleneck.

This routing decision lives in `domain_fronter.rs`. The Google domain list is embedded at compile time.

## Config

`config.full.example.json` from the repo:

```json
{
  "mode": "full",
  "google_ip": "216.239.38.120",
  "front_domain": "www.google.com",
  "script_id": "YOUR_APPS_SCRIPT_DEPLOYMENT_ID",
  "auth_key": "CHANGE_ME_TO_A_STRONG_SECRET",
  "listen_host": "127.0.0.1",
  "listen_port": 8085,
  "socks5_port": 8086,
  "log_level": "info",
  "verify_ssl": true
}
```

Two other examples ship: `config.google-only.example.json` (no Apps Script at all, just Google-edge tunneling for Google properties — useful if you only need YouTube through a blocked connection) and `config.example.json` (standard Apps Script relay).

The `mode` field picks routing: `full` uses both Google-direct and Apps Script relay, `google-only` skips the relay entirely. There's also an upstream SOCKS5 option for chaining non-HTTP protocols through an external xray/v2ray tunnel while keeping HTTP/HTTPS through the Google relay.

## Platform support

Prebuilt binaries for:

- Linux x86_64 and aarch64 (static musl builds for router/embedded use)
- macOS x86_64 and aarch64
- Windows x86_64
- Android 7.0+ as a universal APK

The Android build is the big differentiator from the Python version. It uses `jni` to bridge into a small Android shell app that exposes `VpnService`, and `tun2proxy` to run a userspace TCP/IP stack (via smoltcp) that reads raw packets from VpnService's TUN fd and funnels every TCP/UDP flow through the local SOCKS5. Without the `tun2proxy` piece, VpnService just establishes a TUN device nothing reads from and all traffic black-holes — the README's issue tracker shows this was a real early bug.

The `Cargo.toml` has explicit notes about the non-obvious dependency choices:

- `portable-atomic` for 64-bit atomics on 32-bit MIPS/ARMv5 (routers and OpenWRT targets don't have native 64-bit atomic ops; Rust's std `AtomicU64` won't compile there).
- `libc` for `RLIMIT_NOFILE` bumping because OpenWRT routers ship with low fd limits and browsers fill that up fast under proxy load.
- `eframe` with both `glow` (OpenGL 2+) and `wgpu` (DX12/Vulkan/Metal) backends compiled in. The UI binary picks `glow` by default and falls back to `wgpu` via `MHRV_RENDERER=wgpu` for older Windows hardware, RDP sessions, and VMs without OpenGL 2.0.

Those notes suggest real field reports from users on constrained hardware — the kind of detail that tends to appear in tools aimed at censored regions.

## Two binaries, two audiences

`mhrv-rs` is the headless CLI, for servers, routers, and anything scripted. `mhrv-rs-ui` is the egui desktop app with a config form, live stats, start/stop buttons, and the root-cert install helper. The `ui` is a Cargo feature, not a separate crate — same source tree, conditional compilation.

The egui UI is notable because the Python original doesn't have one; users had to edit JSON by hand and run the CLI. For an Iranian user who just wants VPN-without-a-VPS, the desktop app is a meaningful usability step up.

## Tradeoffs vs the Python original

Everything the Python version does, this version does — but:

- **Startup.** Rust binary starts in tens of milliseconds. Python starts in a couple seconds.
- **Memory.** Rust holds steady around 30-50 MB. Python with httpx/h2 sits around 120-180 MB.
- **Install surface.** Rust needs zero runtime. Python needs a 3.11+ interpreter and pip-installed deps, which is where a lot of the "doesn't work in Iran" support tickets land.
- **Android.** Rust ships a real Android app. Python effectively doesn't work on Android without Termux gymnastics.
- **Feature lag.** Rust is a port; the upstream Python project still moves faster on new relay modes. The Python version currently has a Cloudflare Worker mode and a Cloud Run mode that this port doesn't have yet (as of v1.2.11).

## Security caveats

Same warnings as the Python original:

- The local root CA is a full trust anchor. Anyone who gets `ca.key` from your data dir can MITM every HTTPS site you visit. Don't share the directory, don't sync it to a shared drive.
- `auth_key` in the config is the only gate on your Apps Script deployment. If it leaks (committed to a public repo, posted in a screenshot), anyone can burn your Google quota.
- The project is three days old, 257 stars, unaudited. Rust is memory-safe but the TLS and MITM code paths are the kind of thing that hides logic bugs well.

## Tradeoffs vs VLESS/Xray (same as Python version)

Sits in the same niche as [[masterhttprelayvpn]]: the "zero-budget, low-bandwidth, one-user, no-VPS" end of the circumvention space. The VLESS cluster ([[xray-tutorial]], [[3x-ui]], [[mihomo]], [[xkeen]], [[karing]]) is the "few-users, paid-VPS, higher-quality, supports-everything" end. Mostly Iran-facing; less useful for Russia, where TSPU's CIDR filter targets Google-edge IPs less aggressively but the overall environment is different (see [[russia-vpn-bypass-state-2026-04]]).

## Repo

https://github.com/therealaleph/MasterHttpRelayVPN-RUST — 257 stars, MIT, Rust, v1.2.11. Tagged `iran`, `dpi-bypass`, `domain-fronting`. Homepage link in the repo points back to the Python upstream.

## Related

- [[masterhttprelayvpn]] — the Python original this is a port of
- [[serverless-relay-transport]] — the broader pattern of using a serverless runtime as the circumvention exit
- [[domain-fronting]] — the underlying TLS trick
- [[xray-tutorial]], [[3x-ui]], [[mihomo]], [[karing]] — the VLESS cluster this is the zero-budget alternative to
- [[russia-vpn-bypass-state-2026-04]] — why this particular tool plays a smaller role in the Russian context than in Iran