therealaleph
624914241a
@Montazeran8 noticed two stale doc claims in the ngrok tunnel guide: 1. ngrok.md Step 8 told users to run `mhrv-rs test` to verify a Full-mode tunnel — but `mhrv-rs test` is wired for the apps_script relay path only and refuses to run in Full mode. Fixed to direct users to ipleak.net / whatismyipaddress.com instead. 2. ngrok.md "Renewing the Tunnel" + "Limitations" sections claimed the *.ngrok-free.app URL changes every run. ngrok's free tier now ships with a default static domain per account, so the URL stays the same across runs once assigned. Updated both sections to distinguish static-domain accounts (no CodeFull.gs redeploy needed) from older accounts that opted out. 3. README.md "Limitations" + "After Starting the Tunnel" sections updated to reflect that only Method 1 (cloudflared Quick) has truly volatile URLs. Method 2 (ngrok) keeps the same URL on accounts with a static domain. No code changes — doc-only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
GitHub Actions Full Tunnel
A temporary, repeatable Full tunnel mode for users who cannot or prefer not to
purchase a VPS. Uses GitHub Actions free hosted runners to run the official
mhrv-tunnel-node container for 6-hour sessions at no cost.
Who This Is For
- Users who cannot access international payment methods to purchase a VPS
- Users who need Full tunnel mode occasionally — CAPTCHA-protected sites, streaming, or services that require a real browser
- Users who want to test Full tunnel mode before committing to a permanent VPS
- Users in networks where the standard
apps_scriptmode is sufficient for daily browsing, but Full mode is needed for specific use cases
How It Works
- A GitHub Actions workflow starts the official
mhrv-tunnel-nodeDocker container on a free hosted runner - A tunneling service (cloudflared or ngrok) exposes the container to the internet on a public URL
CodeFull.gsis configured to forward tunnel traffic to this URL- The runner stays alive for 6 hours, then shuts down automatically
- The workflow can be re-triggered at any time for another 6-hour session
Available Methods
Three methods are provided, ordered by setup complexity. Each is documented in its own guide with step-by-step instructions.
| # | Method | Guide | Account Required | URL Behavior | Iran ISP friendly? |
|---|---|---|---|---|---|
| 1 | cloudflared Quick Tunnel | cloudflared-quick.md | None | New URL each session | ⚠️ See note below |
| 2 | ngrok Tunnel | ngrok.md | ngrok (free) | New URL each session | ✅ Works |
| 3 | cloudflared Named Tunnel | cloudflared-named.md | Cloudflare + domain | Permanent URL | ⚠️ See note below |
⚠️ Important — cloudflared methods may not work from Iran ISP. Apps Script outbound runs from Google datacenter IPs, which Cloudflare's anti-bot system flags as bots and serves a 403 / Persian Google Docs error page (#849). This blocks the Apps Script → trycloudflare.com / your-domain step. If you're on Iran ISP, start with Method 2 (ngrok) instead — ngrok's edge IPs are not on Cloudflare's flagged list. cloudflared Methods 1 and 3 may still work for users on networks where Cloudflare's anti-bot heuristics aren't firing against Apps Script's outbound, so they're documented for completeness.
New to Full tunnel mode? If you're on Iran ISP, start with Method 2 (ngrok) — it's the most reliable. If you're on a network where CF anti-bot doesn't fire against Google datacenter IPs, Method 1 (cloudflared Quick) is the simplest (no third-party signup).
Need a stable URL that survives restarts? Use Method 3 — requires a one-time Cloudflare CLI setup but the URL never changes.
Shared Requirements
All methods share these requirements:
| Requirement | Details |
|---|---|
| GitHub account | Free. Repository must be private to keep secrets secure. |
| Google account | Free. Used to deploy CodeFull.gs. |
CodeFull.gs deployed |
See the main project documentation for deployment instructions. |
TUNNEL_AUTH_KEY secret |
A strong password shared between the workflow and CodeFull.gs. |
After Starting the Tunnel
- Run the workflow from your repository's Actions tab
- Copy the
TUNNEL_SERVER_URLfrom the workflow log output - Update the
TUNNEL_SERVER_URLconstant inCodeFull.gs - Deploy
CodeFull.gs(Deploy → New Deployment → Web App) - Configure your
mhrv-rsclient to use the new deployment in Full mode
For Method 1 (cloudflared Quick) the URL is fresh every session, so steps 2–4
must be repeated each time. For Method 2 (ngrok), free-tier accounts now get a
static domain by default — once assigned, the URL is the same across runs
and CodeFull.gs only needs to be updated once. Method 3 uses a permanent
URL — configure CodeFull.gs once and only re-trigger the workflow when
needed.
Limitations
- 6-hour maximum per session. GitHub Actions enforces a 360-minute timeout on hosted runners. Re-trigger the workflow for another session.
- URL changes on restart (Method 1). cloudflared Quick assigns a fresh
*.trycloudflare.comURL at runtime.CodeFull.gsmust be updated and redeployed each session. Method 2 (ngrok) keeps the same URL across runs on accounts with a static domain assigned (the free-tier default). - Shared IP ranges. GitHub-hosted runners share IP ranges with other users. Some websites may already have these IPs flagged.(sometimes need re-run)
- GitHub Actions terms. This workflow is intended for occasional personal use. Review GitHub's Terms for Additional Products and Features and ensure your usage complies.
Compliance Note
This workflow uses GitHub-hosted runners for a purpose adjacent to, but not directly part of, software development on the repository. Usage is low-burden (a single Docker container, moderate outbound traffic for one user) and aligns with GitHub's acceptable use guidelines for development and testing infrastructure. Continuous, high-bandwidth, or commercial use is not recommended. For persistent Full mode operation, a dedicated VPS remains the recommended solution.