Map

MasterHttpRelayVPN-RUST

Toolbox toolboxrustproxyvpndomain-frontingcensorship-circumventiongoogle-apps-scripteguiRustMIT ↳ show in map Markdown
title
MasterHttpRelayVPN-RUST
type
toolbox
summary
Rust port of MasterHttpRelayVPN — zero-dep cross-platform DPI bypass via Google Apps Script relay with egui desktop UI and Android VpnService
tags
rust, proxy, vpn, domain-fronting, censorship-circumvention, google-apps-script, egui
repo
https://github.com/therealaleph/MasterHttpRelayVPN-RUST
language
Rust
license
MIT
created
2026-04-24
updated
2026-04-24

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:

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

Linked from