mhrv-rs — bypass censorship for free, with your own Google account

A small program that runs on your computer and lets you visit blocked websites for free, using a Google Apps Script you deploy in your own free Google account. Your ISP only sees encrypted traffic to www.google.com — it can't tell what you're really visiting.

🇬🇧 English Quick Start · Full Guide (advanced topics) 🇮🇷 راه‌اندازی سریع فارسی · راهنمای کامل (مباحث پیشرفته)

۱. راهنمای تصویری راه اندازی به زبان فارسی (YouTube)
۲. راهنمای جامع متنی راه اندازی به زبان فارسی با تشکر از Kian Irani

What you get

• 🌐 Bypasses DPI / SNI blocking by using Google's edge as a relay
• 💯 Completely free — runs on your own Google account's free tier
• ⚡ One small file (~3 MB), no Python, no Node.js, no dependencies
• 🖥️ Works on Mac, Windows, Linux, Android, OpenWRT routers
• 🦊 Any browser or app that supports HTTP proxy or SOCKS5

How it works (the simple picture)

   you  →  browser  →  mhrv-rs  ──┐
                                  │ ISP only sees:  www.google.com
                                  ▼
                          Google's network
                                  │
                                  ▼
              your free Apps Script  fetches  the real site
                                  │
                                  ▼
                Twitter / ChatGPT / blocked-site of your choice

ISPs can't read inside encrypted HTTPS. They only see the address — www.google.com. The actual page lookup happens inside Google's network, hidden in the encrypted tunnel.

Quick Start

About 5 minutes. You need:

• A free Google account (any Gmail works)
• A computer (Mac, Windows, or Linux)
• Firefox or Chrome

Step 1 — Make the Google Apps Script (one-time)

1. Go to script.google.com, sign in with your Google account
2. Click New project at the top left
3. Delete the default code in the editor
4. Open the file assets/apps_script/Code.gs in this repo, copy all of it, paste into the Apps Script editor (replacing what was there)
5. Find this line near the top:

   const AUTH_KEY = "CHANGE_ME_TO_A_STRONG_SECRET";

   Change CHANGE_ME_TO_A_STRONG_SECRET to a long random string of your own. Keep this string — you'll paste it into the app in Step 3. Treat it like a password.

6. Click 💾 Save (or Ctrl/Cmd+S)
7. Click Deploy (top right) → New deployment
8. Click the gear icon ⚙ next to "Select type" → choose Web app
9. Set:
   • Execute as: Me (your Google account)
   • Who has access: Anyone
10. Click Deploy. Google may ask for permissions — click Authorize access and approve
11. Google shows a Deployment ID (a long random string). Copy it — you'll need it in Step 3.

Tip: if you ever update Code.gs later, don't make a new deployment. Edit the code, then go to Deploy → Manage deployments → ✏️ → Version: New version → Deploy. The Deployment ID stays the same.

Step 2 — Download mhrv-rs

Go to the latest release page and download the file for your computer:

Mac: not sure if Apple Silicon or Intel? Click → About This Mac. If "Chip" says Apple, get arm64. If Intel, get amd64.

Linux: getting a GLIBC error? Use the linux-musl-amd64 file instead — it works on any Linux without dependencies.

Unzip it.

Step 3 — First run

Double-click the launcher:

| Mac | run.command | | Windows | run.bat | | Linux | ./run.sh (in a terminal) |

The first time, it asks for your computer password. This is to install one small certificate so your browser trusts mhrv-rs. The certificate is generated on your computer and never leaves it — no cloud, no Google, nothing remote can use it.

The mhrv-rs window opens. Fill in:

• Apps Script ID(s) → paste the Deployment ID from Step 1
• Auth key → paste the random string you put in Code.gs
• Leave everything else at the defaults

Click Save config, then Start. The status circle goes green if it works.

Test it: click the Test button. It sends one request through the relay and tells you if it worked.

Step 4 — Tell your browser to use mhrv-rs

Firefox (recommended — easiest)

1. Firefox → ☰ menu → Settings
2. Search "proxy" in the search box
3. Click Settings… under Network Settings
4. Choose Manual proxy configuration
5. HTTP Proxy: 127.0.0.1 Port: 8085
6. ☑ Check "Also use this proxy for HTTPS"
7. Click OK

Chrome / Edge

Install the Proxy SwitchyOmega extension and set proxy to 127.0.0.1:8085.

macOS (whole system)

System Settings → Network → Wi-Fi → Details → Proxies → enable both Web Proxy (HTTP) and Secure Web Proxy (HTTPS), both pointing to 127.0.0.1:8085.

Step 5 — Try it

Open any blocked site in your browser. It should load.

If something doesn't work:

• Click Test in the mhrv-rs window — it pinpoints which step is failing
• Look at the Recent log panel at the bottom of the window
• See Common questions below

Common questions

Is this really free? Yes. Google gives every account 20,000 outbound URL fetches per day on the free tier. That's plenty for one person's normal browsing. For a family of 3–4 sharing the same setup, make 2–3 deployments in different Google accounts and add all the IDs.

Is it safe? The certificate stays on your computer — no one else has the private key. Your auth_key is your secret. Google sees the websites you visit through the relay (because Apps Script fetches them on your behalf) — same as any hosted proxy. If you're not OK with that, use Full Tunnel mode with your own VPS — see the full guide.

YouTube videos don't play. YouTube's video chunks come from googlevideo.com, which Apps Script can't reach (Google blocks Apps Script from accessing Google's own video CDN). The page itself loads fine; only video playback is affected. Fix: Full Tunnel + VPS, or add .googlevideo.com to passthrough_hosts in your config (browser hits it directly, but on Iran ISPs it's still throttled).

ChatGPT / Claude / Grok shows a Cloudflare CAPTCHA. Cloudflare flags Google datacenter IPs as bots. Fix: set up an exit node — a small TypeScript handler you deploy on a serverless host (Deno Deploy, fly.io, your own VPS) that bridges Apps Script → your exit node → claude.ai. See assets/exit_node/README.md.

Telegram is unstable. Telegram uses MTProto, which Apps Script doesn't speak. Pair with xray on your machine — see Telegram via xray in the full guide.

ISP blocks script.google.com itself. mhrv-rs has a direct mode that uses only the SNI-rewrite tunnel (no Apps Script). Use it once to access script.google.com to deploy your script, then switch to apps_script mode. See direct mode.

My Google search shows up without JavaScript. The Apps Script User-Agent is fixed to Google-Apps-Script (Google won't let scripts change it), so some sites serve a no-JS fallback. Workaround: add the affected domain to your hosts map so it goes through the SNI-rewrite tunnel with your real browser User-Agent. google.com, youtube.com, fonts.googleapis.com are already on this list by default.

More questions: full FAQ in the long guide.

Need help?

• Search open and closed issues — your problem might already be answered
• Open a new issue with: your config (mask auth_key!), exactly what you tried, exactly what you saw in the log

Credits

Original project: @masterking32/MasterHttpRelayVPN. The idea, the Apps Script protocol, the proxy architecture — all his. This Rust port exists to make client-side distribution easier (single binary, no Python install).

Most of the Rust code in this port was written with Anthropic's Claude, reviewed by a human on every commit.

Support this project

❤️ Donate at sh1n.org — covers hosting and CI runner costs. Starring the repo also helps signal the project is worth keeping alive.

  تو  ←  مرورگر  ←  mhrv-rs  ──┐
                                │ ISP فقط می‌بیند:  www.google.com
                                ▼
                         شبکهٔ گوگل
                                │
                                ▼
            اسکریپت رایگان گوگل تو  سایت اصلی را  باز می‌کند
                                │
                                ▼
              توییتر / ChatGPT / هر سایت مسدودی

   const AUTH_KEY = "CHANGE_ME_TO_A_STRONG_SECRET";