MasterHttpRelayVPN-RUST/assets/github-actions-tunnel/README.md

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_script mode is sufficient for daily browsing, but Full mode is needed for specific use cases

How It Works

1. A GitHub Actions workflow starts the official mhrv-tunnel-node Docker container on a free hosted runner
2. A tunneling service (cloudflared or ngrok) exposes the container to the internet on a public URL
3. CodeFull.gs is configured to forward tunnel traffic to this URL
4. The runner stays alive for 6 hours, then shuts down automatically
5. 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)	Permanent URL	⚠️ .dev TLD blocked on some ISPs
3	cloudflared Named Tunnel	cloudflared-named.md	Cloudflare + domain	Permanent URL	⚠️ See note below

⚠️ ngrok *.ngrok-free.dev block (early 2026). Free-tier ngrok now auto-assigns *.ngrok-free.dev domains exclusively for new accounts (the older *.ngrok-free.app is grandfathered for existing accounts only and cannot be claimed). Some Iran ISPs (TCI, Irancell, IRMCI confirmed via #924) block *.ngrok-free.dev at DNS or TCP. Symptom: curl from your network to your ngrok URL times out, but works from a non-Iran machine. Workarounds: try Method 1 (cloudflared Quick) as a different TLD, or pay $10/mo for ngrok Personal plan to get *.ngrok.app instead.

⚠️ cloudflared methods may not work from Iran ISP. Apps Script outbound runs from Google datacenter IPs, which Cloudflare's anti-bot system sometimes flags as bots and serves a 403 / Persian Google Docs error page (#849). 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 — try them and check.

New to Full tunnel mode? Try Method 2 (ngrok) first — it's the fastest setup and gives a permanent URL on the free tier. If *.ngrok-free.dev is blocked on your ISP (curl times out), switch to Method 1 (cloudflared Quick) — different TLD, sometimes passes where ngrok's .dev doesn't. If both fail, see the Alternative hosts section below.

Need a stable URL on a CF-friendly domain? Use Method 3 — requires a one-time Cloudflare CLI setup with your own domain.

Alternative hosts (when GitHub Actions tunnels don't work)

If both ngrok and cloudflared paths are blocked on your network, run mhrv-tunnel-node somewhere that doesn't rely on a third-party tunnel:

• HuggingFace Spaces (Docker SDK): free, permanent *.hf.space URL, no tunnel layer needed. Create a Space → pick Docker SDK → small Dockerfile that runs ghcr.io/therealaleph/mhrv-tunnel-node:latest. 16 GB storage, 2 vCPU. Most Iran-friendly option in 2026.
• Replit (Deno repl): signup with email, free tier. Run mhrv-tunnel-node and the Repl exposes a public URL.
• Your own VPS: Hetzner / Vultr / DigitalOcean / ArvanCloud. ~$3-5/mo. See tunnel-node README for Docker setup.

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

1. Run the workflow from your repository's Actions tab
2. Copy the TUNNEL_SERVER_URL from the workflow log output
3. Update the TUNNEL_SERVER_URL constant in CodeFull.gs
4. Deploy CodeFull.gs (Deploy → New Deployment → Web App)
5. Configure your mhrv-rs client 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.com URL at runtime. CodeFull.gs must 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.