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

ngrok Tunnel

Run a Full tunnel for 6 hours using an ngrok account (free tier). ngrok provides a public URL that exposes the tunnel-node running on GitHub Actions.

Prerequisites

• A GitHub account (free)
• An ngrok account (free — sign up at ngrok.com)
• CodeFull.gs deployed as a Google Apps Script Web App

Setup

Step 1: Get Your ngrok Authtoken

1. Go to dashboard.ngrok.com and sign in
2. Copy your authtoken from the Getting Started or Your Authtoken section

Step 2: Create the Repository

If you already have a repository from another method, you can reuse it. Otherwise:

1. Go to github.com and sign in
2. Click the + icon in the top-right corner, then New repository
3. Enter a repository name (e.g., my-tunnel)
4. Select Private (recommended — keeps your secrets secure)
5. Click Create repository

Step 3: Add the Secrets

1. In your repository, go to Settings > Secrets and variables > Actions

2. Click New repository secret and add:

   Name	Value
   TUNNEL_AUTH_KEY	A strong password. You will also set this in CodeFull.gs.
   NGROK_AUTH_TOKEN	Your ngrok authtoken from Step 1.

3. Click Add secret for each

Step 4: Add the Workflow

1. In your repository, go to the Actions tab
2. Click New workflow
3. Click the set up a workflow yourself link
4. Delete the default content and paste the contents of ngrok.yml [here]
5. Click Commit changes..., add a commit message, then click Commit changes

The workflow file will be saved to .github/workflows/ngrok.yml.

Step 5: Run the Workflow

1. Go to the Actions tab
2. Select Full Tunnel (ngrok) from the left sidebar
3. Click Run workflow > Run workflow

The workflow will start immediately.

Step 6: Get the Tunnel URL

1. Click on the running workflow to see live logs
2. Wait for the Expose tunnel step to complete (about 10 seconds)
3. Look for the ::notice::Tunnel URL: line in the log output
4. Copy the URL — it will look like https://abc123.ngrok-free.app

Step 7: Configure CodeFull.gs

Open CodeFull.gs in the Google Apps Script editor and update these constants:

const TUNNEL_SERVER_URL = "https://abc123.ngrok-free.app";
const TUNNEL_AUTH_KEY = "the-secret-you-set-in-step-3";

Deploy: Deploy > New Deployment > Web App. Copy the new Deployment ID and update your mhrv-rs config.

Step 8: Verify

mhrv-rs test is wired only for the apps_script relay path; in Full mode it refuses to run. To verify a Full-mode tunnel, visit https://ipleak.net (or https://whatismyipaddress.com) through your proxy — you should see a GitHub Actions or ngrok IP address.

How It Works

1. GitHub Actions starts a Docker container running mhrv-tunnel-node on port 8080
2. ngrok creates a secure tunnel using your authtoken, assigning a temporary *.ngrok-free.app URL that routes to localhost:8080 on the runner
3. The workflow extracts this URL from the ngrok API and displays it
4. CodeFull.gs forwards tunnel operations to this URL over HTTPS
5. The runner stays alive for 6 hours, then shuts down automatically

Renewing the Tunnel

The tunnel shuts down after 6 hours. To start a new session:

1. Go to the Actions tab
2. Select Full Tunnel (ngrok)
3. Click Run workflow > Run workflow
4. Check the tunnel URL in the logs. Each ngrok free account gets one auto-assigned dev domain that's permanent across runs — the URL is the same every time you re-run the workflow, so no CodeFull.gs update is needed after the initial setup.

Limitations

• Requires an ngrok account (free tier: 1 online tunnel, limited connections per minute).
• ngrok TLD note: ngrok handed out *.ngrok-free.app domains until early 2026; new free-tier accounts now get *.ngrok-free.dev instead, with no way to switch back. Some Iran ISPs block *.ngrok-free.dev at the DNS layer. If your tunnel works on a non-Iran network but curl from your Iran network times out at TCP, the .dev block is why. Workarounds:
  • Switch to cloudflared Quick (Method 1) — different TLD, often passes where ngrok's .dev doesn't.
  • Switch to HuggingFace Spaces (Docker) — run tunnel-node directly on a Space, get a permanent *.hf.space URL with no tunnel layer.
  • Pay for ngrok's $10/mo Personal plan to get a *.ngrok.app domain (the older, more widely allowlisted TLD).
• 6-hour maximum per session (GitHub Actions limit).
• Slightly higher latency than cloudflared methods (extra hop through ngrok's relay servers).

Troubleshooting

Problem	Solution
ngrok authentication fails	Verify NGROK_AUTH_TOKEN matches the token in your ngrok dashboard.
Workflow fails at Docker step	GitHub Actions may be pulling the image for the first time. Wait 2-3 minutes and retry.
No tunnel URL appears in logs	Check that the Expose tunnel step completed. The URL is fetched from the ngrok API — allow 10 seconds for the tunnel to establish.
Connection limit reached	ngrok's free tier limits connections per minute. Wait a moment and retry.
CodeFull.gs returns 502 or timeout	Verify the tunnel URL is correct and the workflow is still running. Check that TUNNEL_AUTH_KEY matches in both the secret and CodeFull.gs.