MasterHttpRelayVPN: Domain-Fronted HTTP Proxy Tunneling Through Google Apps Script

The Problem MasterHttpRelayVPN Solves

Network filters that block access to specific websites typically work by inspecting DNS queries or the destination address of TCP connections. Domain fronting circumvents this category of filter. The technique routes a TLS connection to a large infrastructure provider (in this case Google) while encoding the actual intended destination in the encrypted part of the request. The network filter sees only a connection to Google's servers and has no visibility into the encrypted payload specifying the real destination.

MasterHttpRelayVPN implements this using Google Apps Script as the relay endpoint. A user deploys a small script to their Google account. The local proxy on the user's computer receives browser traffic, forwards it to the Apps Script URL (which is hosted on Google's infrastructure), and the Apps Script fetches the actual destination page and returns it. The network path the filter sees is:

Browser -> Local proxy -> Google front -> Your Apps Script relay -> Target site
                         network filter sees a Google-facing connection

The README describes two main techniques: MITM (Man in the Middle) for TLS interception, and domain fronting for making traffic appear to target Google. For sites that block Google's egress IP (such as ChatGPT and some Cloudflare-protected services), an optional exit node through Cloudflare Workers or a VPS routes the traffic through a different outbound IP.

The project is maintained by the MasterDnsVPN Telegram community. The repository includes a Persian README translation (README_FA.md), and the Telegram channel name @MasterDnsVPN indicates the primary user base is in Iran and similar network-restricted environments.

Deploying the Google Apps Script Relay

Before running the local proxy, a relay must be deployed to a Google account. The README describes this as a two-minute process that requires only a Google account.

Open Google Apps Script at script.google.com, create a new project, delete the default content, paste the contents of apps_script/Code.gs from the repository, and set the AUTH_KEY constant to a unique secret:

const AUTH_KEY = "your-secret-password-here";

Then deploy it as a web app with execution set to "Me" and access set to "Anyone." Copy the Deployment ID. The AUTH_KEY must match the auth_key value in the local config.json. If they differ, the proxy will return an unauthorized error.

The relay only needs to be deployed once. If Google Apps Script's rate limits become a problem at higher usage volumes, the README documents an exit node option that routes traffic through a Cloudflare Worker or a VPS instead of returning directly from the Apps Script.

Installing and Running the Local Proxy

The local proxy requires Python 3.10 or later. The repository can be obtained with Git:

git clone https://github.com/masterking32/MasterHttpRelayVPN.git
cd MasterHttpRelayVPN

On Linux and macOS, the startup script handles the rest:

chmod +x start.sh
./start.sh

On Windows the equivalent is start.bat. The launcher creates a Python virtual environment, installs dependencies from requirements.txt, and opens the setup wizard if no config.json is found. The setup wizard is implemented in setup.py. It reads config.example.json as a base, prompts for the Deployment ID and AUTH_KEY, generates a random 32-character auth key if the user wants one, and writes the finished config.json. The source shows it also handles an NO_COLOR environment variable for terminal output that does not support ANSI escape codes.

After the proxy starts, configure the browser to use: - HTTP proxy: 127.0.0.1 port 8085 - SOCKS5 proxy: 127.0.0.1 port 1080

A CA certificate is installed automatically. Certificate warnings in the browser indicate the CA was not installed correctly; the README's Troubleshooting section covers this case. The SOCKS5 port can also be used with Telegram's proxy settings: the README shows the direct link format https://t.me/socks?server=127.0.0.1&port=1080.

How the MITM Interception and HTTP/2 Work

The proxy intercepts TLS connections using a locally generated CA certificate rather than letting the browser connect directly to the destination. This MITM approach allows the proxy to read and forward HTTPS traffic through the Apps Script relay, which only accepts HTTP. The cryptography package in requirements.txt provides the certificate manipulation:

cryptography>=41.0.0
h2>=4.1.0
certifi>=2024.1.0; sys_platform != "win32"
brotli>=1.1.0
zstandard>=0.22.0

The h2 package adds HTTP/2 multiplexing on the connection between the local proxy and the relay. Modern websites send Brotli-compressed responses, handled by the brotli package. Some CDNs now use Zstandard compression, handled by zstandard.

The README states that YouTube safe search and live streaming now bypass by default, so the youtube_via_relay option or a separate exit node is no longer needed for those services. ChatGPT and services that use Cloudflare Turnstile block Google's exit IP and still require an exit node.

Docker Deployment and LAN Sharing

The repository includes a Dockerfile and docker-compose.yml for containerized deployment. The Dockerfile uses python:3.13-slim and excludes config.json and the CA directory from the image at build time:

name: masterhttprelayvpn
services:
  proxy:
    build: .
    container_name: masterhttprelayvpn
    restart: unless-stopped
    ports:
      - "8085:8085"
      - "1080:1080"
    volumes:
      - ./config.json:/app/config.json:ro
      - ./ca:/app/ca

The config.json and CA directory are mounted at runtime, keeping secrets out of the image. The docker-compose.yml names the network masterhttprelayvpn-net.

For sharing the proxy on a local network, the README links to LAN_SHARING.md, which covers Android, iOS, and other computers. The container's CMD uses --host 0.0.0.0, which is required for the proxy to be reachable from outside the container when running in Docker.

Security Constraints and Legal Disclaimer

The README includes a security warning about what should never be shared: the config.json file, the auth_key, the ca/ directory, and an exit node URL combined with a valid pre-shared key. Sharing these together gives a third party full use of the relay and CA.

The legal disclaimer in the README is explicit on four points. The developers are not responsible for damages resulting from use. Users are responsible for complying with Google's Terms of Service, including its acceptable use rules and quota limits for Apps Script, and misuse can lead to account suspension. Users are also responsible for compliance with local, national, and international laws. The README states the project is provided for educational, testing, and research use. It also notes that running the project outside controlled environments may affect networks, accounts, proxies, certificates, or connected systems, and that the user is solely responsible.

The docs/ directory contains separate documentation files for getting started, exit node deployment, LAN sharing, configuration reference, security notes, troubleshooting, Docker, and architecture. The Configuration reference at docs/CONFIGURATION.md is the place to find all available config.json keys and their defaults.

For teams evaluating similar tools: Shadowsocks and V2Ray are widely used alternatives that operate as dedicated proxy servers rather than routing through cloud function infrastructure. They offer more predictable performance and do not depend on a free-tier service quota, but require a VPS to deploy.

Maintenance Status and License

The last push to masterking32/MasterHttpRelayVPN was on 2026-06-09. The default branch is python_testing rather than main or master. The repository is not archived, and the README mentions an active Telegram channel at t.me/MasterDnsVPN and a group at t.me/MasterDnsVPNGroup for support and updates. The project also mentions an ad blocker filter list from PersianBlocker as a related resource.

The project is MIT licensed. The README credits a contributor named Abolix for making the project possible and helping maintain it. Donations are accepted through the TON network at masterking32.ton, EVM-compatible networks, and TRC20 on TRON, according to the README. The Persian README translation was generated with AI according to a note in that file.

Editorial conclusion

MasterHttpRelayVPN is a practical tool for individuals in networks that block specific domains but permit connections to Google's infrastructure. The setup requires only a free Google account and about two minutes to deploy the relay, and the local launcher handles virtual environment creation and configuration on first run. It is not appropriate for high-volume use because Google Apps Script has rate limits and quota restrictions. Teams routing organizational traffic should read the legal disclaimer and Security Notes before using this with other people's devices. The last push was on 2026-06-09, and the repository is MIT licensed.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. masterking32/MasterHttpRelayVPN on GitHub
4. Project website
5. README