Map

MasterHttpRelayVPN

Toolbox toolboxpythonproxyvpndomain-frontingcensorship-circumventiongoogle-apps-scriptPythonMIT ↳ show in map Markdown
title
MasterHttpRelayVPN
type
toolbox
summary
Python proxy that fronts HTTPS traffic through a free Google Apps Script relay
tags
python, proxy, vpn, domain-fronting, censorship-circumvention, google-apps-script
repo
https://github.com/masterking32/MasterHttpRelayVPN
language
Python
license
MIT
created
2026-04-21
updated
2026-04-24

See also masterhttprelayvpn-rust — a Rust port by @therealaleph (first commit 2026-04-21, currently v1.2.11) that keeps the same architecture but ships as a static binary with an egui desktop UI and a real Android build via VpnService. Recommended for users who can't get a Python runtime working in their environment, which is a significant fraction of the target audience.

A local HTTP+SOCKS5 proxy that tunnels your traffic through a free Google Apps Script deployment, making the visible traffic look like HTTPS to www.google.com. No VPS, no paid server, no domain — just a Google account. Aimed at users in censored networks (the repo ships an English and Persian README).

How it works

Four moving parts:

  1. Local proxy on the user's machine. Listens on 127.0.0.1:8085 (HTTP/CONNECT) and 127.0.0.1:1080 (SOCKS5). The browser points at it like a normal proxy.
  2. MITM layer for HTTPS. On first run the tool generates a CA (ca/ca.crt), auto-installs it into the OS/Firefox trust store, and uses it to terminate browser TLS. This is what makes HTTPS requests inspectable so the outer request can be reshaped.
  3. Fronting transport. The reshaped request opens a TLS connection to a Google-owned IP (default 216.239.38.120), sending SNI www.google.com. Inside that connection it sends HTTP/2 to script.google.com/macros/s/<DEPLOYMENT_ID>/exec with a JSON body describing the real request. See domain-fronting.
  4. Google Apps Script relay. Code.gs runs on Google's serverless JS runtime, checks a shared AUTH_KEY, calls UrlFetchApp.fetch() against the real target, and returns the response body. No state, no account linkage beyond the deployment's owner.
┌─────────┐   ┌──────────────┐   ┌────────────────┐   ┌──────────┐
│ Browser │──►│ Local proxy  │──►│ SNI: google    │──►│  Apps    │──► Target site
│         │◄──│ (MITM + HTTP)│◄──│ Host: script.. │◄──│  Script  │◄──
└─────────┘   └──────────────┘   └────────────────┘   └──────────┘

The censor's DPI/SNI filter sees a TLS handshake to www.google.com. The Host: header inside the encrypted tunnel points to a different Google property (script.google.com), which Google's own CDN happily routes.

Modes

Beyond the default Apps Script relay, the same client speaks three other fronting backends:

Mode Relay Notes
apps_script script.google.com/macros/s/<id>/exec Free. Apps Script daily quota becomes the ceiling.
google_fronting Your Cloud Run service behind Google's CDN Paid (Cloud Run), but no quota surprises.
domain_fronting Cloudflare Worker Free tier has request limits; uses domain-fronting on Cloudflare.
custom_domain Your own domain on Cloudflare Direct (no fronting), for when censorship doesn't target your domain.

The load-balancing mechanism is just round-robin over a script_ids array — user deploys Code.gs N times to N Google accounts, stitches the IDs together, and the client spreads load.

Configuration

config.json is small. The three values that matter:

{
  "mode": "apps_script",
  "script_id": "AKfy...YOUR_DEPLOYMENT_ID...",
  "auth_key": "your-secret-password-here"
}

auth_key must match the AUTH_KEY constant in Code.gs — that's the only thing preventing anyone who guesses your deployment ID from using your relay. There's no TLS pinning, no rotating tokens, no per-request signature. Given that Apps Script deployment IDs are long random strings, this is adequate obscurity-plus-secret, but not robust auth.

Tradeoffs vs VLESS/Xray-based circumvention

This tool sits in a different niche from the VLESS-based cluster (xray-tutorial, 3x-ui, mihomo, xkeen, happ-proxy):

  • Setup cost. MasterHttpRelayVPN needs a Google account and two clicks in Apps Script. A VLESS setup needs a VPS ($5/mo minimum), a domain, TLS certs, and an Xray config. Massive difference.
  • Performance. Every request pays the cost of HTTP-over-JSON-over-UrlFetchApp. Latency is noticeably higher than a raw VLESS tunnel, and bandwidth is bounded by Apps Script's quota.
  • Blocking resistance. Google IPs are hard to block in most countries because so much infrastructure depends on them. VLESS servers on random IPs are easier to add to block lists. On the other hand, a censor that does pattern-match on TLS ClientHellos (like Iran's DPI) can fingerprint the specific front by JA3/JA4; this tool does nothing to hide that the client is Python+httpx/h2.
  • Account tie. If Google detects the relay abuses Apps Script quotas/ToS, they suspend the script or the account. VLESS servers have no such single-vendor dependency.

So this is the "zero-budget, low-bandwidth, one-user" end of the circumvention space. The VLESS cluster is the "few-users, paid-VPS, higher-quality" end.

Security notes

  • The local CA is a root trust anchor. If anyone else gets ca/ca.key, they can intercept every HTTPS site the user visits. The project tells users not to share ca/, but this is standard MITM-proxy risk.
  • auth_key is the only gate on the Apps Script endpoint. If it leaks (e.g. committed to git), attackers can use the user's Google quota.
  • The project is four days old (created 2026-04-20) with 418 stars. Active, but unaudited.

Repo

https://github.com/masterking32/MasterHttpRelayVPN — 418 stars, MIT, Python on python_testing branch. Maintainer acknowledges @abolix for the underlying approach. Persian-language Telegram support channel at @masterdnsvpn suggests the primary user base is inside Iran.

Linked from