MasterHttpRelayVPN-RUST/docs/android.md

Android app

Full guide for the mhrv-rs Android app: install, first-run setup, troubleshooting, known limits.

• Overview
• Requirements
• 1. Install the APK
• 2. Deploy the Apps Script
• 3. Enter your config in the app
• 4. Run the SNI tester
• 5. Install the MITM certificate
• 6. Start the tunnel
• UI quick reference
• Known limitations
• Troubleshooting
• Uninstall

---

Overview

The Android app is the exact same mhrv-rs Rust crate that powers the desktop build, wrapped in a Compose UI and fed a TUN file descriptor via VpnService + tun2proxy. Every app on the device is routed through the proxy — no per-app setup.

Any app on the device
        │
        ▼
VpnService TUN  ──► tun2proxy (in-process)
                        │
                        ▼
                Local SOCKS5 listener  ──► mhrv-rs dispatcher
                                                 │
                         ┌───────────────────────┤
                         ▼                       ▼
               sni-rewrite tunnel        Apps Script relay
               (Google-owned hosts       (everything else,
                direct to google_ip)     via your /exec URL)

Setup time: ~10 minutes if your Apps Script deployment already exists, ~15 min if you're deploying fresh.

---

Requirements

Android version	7.0 (API 24) or later
Device architecture	Any. The APK is universal: arm64-v8a, armeabi-v7a, x86_64, x86
Google account	Yes — you'll deploy the Apps Script under it. A throwaway Gmail works
Screen lock	PIN, pattern, password, or biometric + fallback. Required by Android for user-CA install. Can be removed after install; the cert stays trusted
Data usage	~5 MB for the APK, then ~2 MB overhead per GB of browsing (base64 + JSON wrapping)

Scope note. mhrv-rs relays through Apps Script. That's what makes it cheap and DPI-resilient, but it's also what imposes the known limitations below. If you're evaluating against a real VPN (WireGuard/Tailscale/OpenVPN), skim that section first.

---

1. Install the APK

1. On your phone, open the browser and go to https://github.com/therealaleph/MasterHttpRelayVPN-RUST/releases/latest.
2. Download mhrv-rs-android-universal-v*.apk.
3. Tap the download to open the installer.
4. When Android asks "Allow this source to install apps?":
   • Tap Settings
   • Toggle Allow from this source
   • Tap ← Back → Install
5. Tap Open once install finishes.

If Android refuses with "App not installed": an old build signed with a different key is still present. Settings → Apps → mhrv-rs → Uninstall, then try again. (From v1.0.2 onward this is a one-time thing — updates are signed with a stable key.)

---

2. Deploy the Apps Script

Skip this step if you already have a working /exec URL.

Do this on a laptop — it's a browser-heavy flow that's painful on a phone.

1. Go to https://script.google.com → New project.

2. Copy the full contents of assets/apps_script/Code.gs from this repo.

3. In the script editor, select the default function myFunction() {} and paste over it.

4. Find the line near the top:

   const AUTH_KEY = "CHANGE_ME_TO_A_STRONG_SECRET";
   

   Replace the placeholder with a strong random secret (20+ chars, letters + digits). Save this value — you'll paste it into the app too.

5. File → Save (⌘S / Ctrl+S). Name the project something like mhrv-relay.

6. Deploy → New deployment.

7. Click the gear icon → Web app. Fill in:

   Field	Value
   Description	mhrv-relay v1 (or whatever)
   Execute as	Me
   Who has access	Anyone

8. Click Deploy. First time only: Google asks for permissions.

   • Click Authorize access → pick your account
   • On "Google hasn't verified this app" → Advanced → Go to <project name> (unsafe) → Allow

9. Copy the Web app URL. It looks like https://script.google.com/macros/s/AKfyc.../exec.

What the script does

It receives POST { method, url, headers, body_base64 } from our proxy, calls UrlFetchApp.fetch(url, ...) inside Google's datacenter, and returns { status, headers, body_base64 }. DPI bypass comes from us connecting to script.google.com using a different TLS SNI than the HTTP Host header — the ISP sees www.google.com, Google's edge routes by the Host header inside the encrypted stream.

---

3. Enter your config in the app

Back on the phone:

Field	What to enter
Deployment URL(s) or script ID(s)	The /exec URL you copied. You can paste multiple — one per line — and the proxy will round-robin between them (useful when you hit the 20k/day per-script quota)
auth_key	The exact string you put in AUTH_KEY inside Code.gs
google_ip	Leave the default. The next step will auto-populate it
front_domain	Leave at www.google.com

Tap anywhere outside the text fields to dismiss the keyboard.

---

4. Run the SNI tester

Before starting the tunnel, verify the outbound leg works. Expand SNI pool + tester and tap Test all.

Result	Meaning	Action
✅ Green check + NNN ms	google_ip is reachable + accepts the SNI	Proceed
❌ connect timeout on every row	Configured google_ip is unreachable	Tap Auto-detect google_ip under the Network card, then Test all again
❌ connect timeout on some rows	Those specific SNIs are DPI-filtered on your network	Leave them unchecked; rotation pool uses only ticked boxes
❌ dns: ...	Device can't resolve www.google.com at all	Fix Wi-Fi / airplane mode

If you tap Auto-detect and it still fails on every row, your network is blocking Google's edge entirely — mhrv-rs can't help there.

---

5. Install the MITM certificate

The proxy terminates TLS locally (re-encrypts before routing through Apps Script), so your phone needs to trust a cert we minted on first run.

1. In the app, tap Install MITM certificate.

2. The confirmation dialog shows the certificate fingerprint. Tap Install.

3. The app:

   • saves a PEM copy to Downloads/mhrv-ca.crt
   • opens the Android Settings app

4. If you don't have a screen lock — Android will prompt you to set one now. You have to. User CAs require it. You can remove it after install; the cert stays trusted.

5. In Settings, tap the search bar at the top and type CA certificate. Open the result labelled "CA certificate" (or "Install CA certificate" on some OEMs).

   Don't pick "VPN & app user certificate" or "Wi-Fi certificate" — wrong category, won't work.

   Searching is more reliable than navigating menus: Pixel/Samsung/Xiaomi all bury CA install under different paths, but all of them index it under "CA certificate" in search.

6. Android warns "Your network may be monitored by an unknown third party". That's us. Tap Install anyway.

7. Pick Downloads → tap mhrv-ca.crt. Give it a friendly name (or accept the default). Tap OK.

8. Switch back to the mhrv-rs app. A snackbar confirms Certificate installed ✓ — the app verifies by fingerprint against AndroidCAStore.

   If it says "not yet installed", repeat step 5.

Why can't the app install the cert directly?

Android 11 removed the inline KeyChain.createInstallIntent flow. That intent used to open a category picker directly inside the app. On current Android it opens a dead-end dialog with just a Close button — Google wants CA installs to be deliberate. We do the grunt work (save file, open Settings, verify afterwards), but the manual navigation step is unavoidable.

---

6. Start the tunnel

1. Tap Start.
2. Android shows the VPN-permission dialog: "mhrv-rs wants to set up a VPN connection...". Tap OK.
3. A key icon appears in the status bar. That's your VPN indicator.
4. Open Chrome. Try https://www.cloudflare.com, https://yahoo.com, https://discord.com as stress tests — all should render normally.

Expand Live logs to watch the traffic flow:

Log line	What it means
SOCKS5 CONNECT -> <host>:443	Browser opened a TCP flow; TUN captured it
dispatch <host>:443 -> MITM + Apps Script relay	Routing decision
MITM TLS -> <host>:443 (sni=<host>)	Our leaf cert was accepted by the browser
relay GET https://<host>/...	Forwarded to Apps Script
preflight 204 <url>	CORS preflight we answered ourselves (normal, don't worry about these)

---

UI quick reference

Control	Location	Notes
Deployment URL(s) or script ID(s)	Apps Script relay section	One per line; round-robin dispatch
auth_key	Apps Script relay section	Must match AUTH_KEY in Code.gs
google_ip / front_domain	Network section	Auto-detect button fills google_ip via DNS
Auto-detect google_ip	Under the Network row	Re-resolves www.google.com + repairs front_domain if corrupted to an IP
SNI pool + tester	Collapsible	Checkboxes for rotation; per-row Test + Test all
Advanced	Collapsible	verify_ssl, log_level, parallel_relay, upstream_socks5
Start / Stop	Bottom row	2-second debounce between taps
Install MITM certificate	Below Start/Stop	Save PEM → open Settings → search "CA certificate"
Live logs	Collapsible (below the Install button)	500ms poll of the proxy's log ring buffer
v1.0.x (version badge)	Top bar, right	Tap to check GitHub for a newer release

---

Known limitations

Read this before reporting a bug — most "it doesn't work" reports fall into one of these.

Cloudflare Turnstile ("Verify you are human") loops

On Cloudflare-protected sites that challenge every request, you'll solve the Turnstile, reach the page, then get challenged again on the next click. This is inherent to the Apps Script relay model:

Factor	Normal browser	Apps Script relay
Egress IP	Stable (your ISP)	Rotates across Google's datacenter pool per request
User-Agent	Chrome's	Fixed Google-Apps-Script (locked by Google; we can't override)
TLS JA3/JA4	Chrome's	Google-datacenter's

Cloudflare's cf_clearance cookie is bound to the (IP, UA, JA3) tuple the challenge was solved against. Different IP next request → re-challenge.

Sites that only gate the first page load (most of CF's Bot Fight Mode customers) work fine after one solve. Sites that challenge every request (crypto exchanges, adult, some forums) fundamentally can't hold a session through this architecture — use a different tunnel for those.

UDP / QUIC (HTTP/3) doesn't go through

The SOCKS5 listener only handles CONNECT, not UDP ASSOCIATE. Chrome tries HTTP/3 first and falls back to HTTP/2 over TCP, which works fine. Effect: slightly slower first connect, everything else normal.

IPv6 leaks

The TUN only routes IPv4 (addRoute 0.0.0.0/0). IPv6 goes out your normal interface, including WebRTC. If you're using mhrv-rs for privacy rather than DPI bypass, disable IPv6 on your Wi-Fi network entirely.

Apps Script daily quota

Each /exec has a daily execution limit (20k/day for consumer Google accounts, higher for Workspace). Heavy streaming or infinite-scroll sites burn through it. Mitigation: deploy 2–3 scripts, paste all their /exec URLs into the app, one per line — the proxy round-robins.

Most non-browser apps ignore user CAs

By default, Android apps opt out of trusting user-installed CAs (Android 7+ Network Security Config default). Banking apps, Netflix, Spotify, most messengers — they'll fail with cert errors through mhrv-rs. The TUN routes their traffic to us; they just refuse our leaf. Only apps that explicitly opt in (browsers, curl, some developer tools) will work. This is a general MITM-proxy limitation.

---

Troubleshooting

Symptom	Likely cause	Fix
504 Relay timeout in Chrome	Apps Script deployment not responding	Re-check the /exec URL (must end in /exec, not /dev). Watch Live logs for Relay timeout vs connect: errors
NET::ERR_CERT_AUTHORITY_INVALID	MITM CA not installed / not found	Redo step 5. Make sure you picked "CA certificate" in Settings, not VPN or Wi-Fi
NET::ERR_CERT_COMMON_NAME_INVALID on Cloudflare sites	Pre-v1.0 bug	Upgrade to v1.0.0 or later
JS parts of a site don't load	Pre-v1.0 OPTIONS rejection	Upgrade to v1.0.0+. If still present: Live logs → grep for Relay failed, report
All SNIs time out in the tester	google_ip is stale (Google rotated the A record)	Tap Auto-detect google_ip
SNI tester red on some rows only	Those SNIs are DPI-filtered on your network	Uncheck the failing ones in the rotation pool
App closes when tapping Stop	Was a v1.0.0/1.0.1 race bug	Upgrade to v1.0.2. If still present on v1.0.2+: adb logcat -s MhrvVpnService mhrv-crash mhrv_rs and report
INSTALL_FAILED_UPDATE_INCOMPATIBLE when upgrading	Old APK signed with a different key (pre-v1.0.2)	Uninstall first, then install the new APK. Only a one-time thing — v1.0.2 onward has a stable signature
Chrome white-pages with no error	Often a rendering bug on the emulator with software GPU	Test on real hardware. Check Live logs to verify the relay is actually making requests
Cloudflare Turnstile loop	Known limitation	No fix inside this architecture
Banking/streaming apps show cert errors	Known limitation	No fix — app chose not to trust user CAs

Collecting a useful log

If you need to report a bug:

adb logcat -c                              # clear
# reproduce the issue in the app
adb logcat -d | grep -E "MhrvVpnService|mhrv_rs|mhrv-crash|tun2proxy" > mhrv.log

Attach mhrv.log to your issue. Also include:

• Android version (Settings → About phone → Android version)
• OEM (Pixel / Samsung / Xiaomi / …)
• App version (tap the version badge in the top bar)
• What you did, what you expected, what happened

---

Uninstall

1. Settings → Apps → mhrv-rs → Uninstall.
2. Optional: remove the MITM CA — Settings → Security → Encryption & credentials → User credentials → mhrv-rs MITM CA → Remove. (On OEMs where that path is buried, search Settings for user credentials.)
3. The VPN profile is auto-revoked on uninstall — nothing to clean up there.