# MasterHttpRelayVPN

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

```json
{
  "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](https://github.com/abolix) for the underlying approach. Persian-language Telegram support channel at [@masterdnsvpn](https://t.me/masterdnsvpn) suggests the primary user base is inside Iran.

## Related

- [[masterhttprelayvpn-rust]] — Rust port with static binary, egui UI, Android VpnService support
- [[serverless-relay-transport]] — the broader pattern this tool pioneered in the Iran-facing market
- [[domain-fronting]] — the underlying censorship-circumvention technique
- [[xray-tutorial]], [[3x-ui]], [[mihomo]], [[xkeen]] — the VLESS-based cluster this tool is the minimalist alternative to
- [[happ-proxy]] — similar target audience (censored markets), different technical approach
- [[russia-v2ray-rules-dat]] — rule files for the other major censorship-heavy audience