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](https://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](https://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](https://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:

```javascript
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](https://dashboard.ngrok.com). |
| 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`. |

[here]: ngrok.yml