MasterHttpRelayVPN-RUST/assets/github-actions-tunnel/cloudflared-named.md

cloudflared Named Tunnel

Run a Full tunnel with a permanent, unchanging URL using a Cloudflare account and a custom domain. The tunnel URL never changes between restarts — configure CodeFull.gs once and only re-trigger the workflow when needed.

Prerequisites

• A GitHub account (free)
• A Cloudflare account with a domain
• cloudflared installed on your local machine for one-time setup
• CodeFull.gs deployed as a Google Apps Script Web App

One-Time Local Setup

These steps are performed once on your local machine. They create a named tunnel on Cloudflare and route your domain to it.

Step 1: Install cloudflared

Linux (Debian/Ubuntu):

curl -L --output cloudflared.deb \
  https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb

macOS:

brew install cloudflared

Windows: Download the installer from the cloudflared releases page.

Step 2: Authenticate with Cloudflare

cloudflared tunnel login

This opens a browser window. Select your domain and authorize.

Step 3: Create a Named Tunnel

cloudflared tunnel create my-tunnel

This outputs a tunnel ID (a UUID) and creates a credentials file at:

~/.cloudflared/<TUNNEL_ID>.json

Copy the tunnel ID — you will need it later.

Step 4: Route Your Domain

cloudflared tunnel route dns my-tunnel tunnel.yourdomain.com

Replace tunnel.yourdomain.com with the actual subdomain you want to use. This creates a DNS record on Cloudflare pointing to your tunnel.

Step 5: Get the Credentials File

cat ~/.cloudflared/<TUNNEL_ID>.json

Copy the entire JSON output. You will use this as the CLOUDFLARE_TUNNEL_CREDENTIALS secret in GitHub Actions.

GitHub Setup

Step 6: 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 7: Add the Secrets

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

2. Click New repository secret and add each of the following:

   Name	Value
   TUNNEL_AUTH_KEY	A strong password. You will also set this in CodeFull.gs.
   CLOUDFLARE_TUNNEL_ID	The tunnel ID from Step 3.
   CLOUDFLARE_TUNNEL_HOSTNAME	The subdomain you configured in Step 4 (e.g., tunnel.yourdomain.com).
   CLOUDFLARE_TUNNEL_CREDENTIALS	The entire JSON contents of the credentials file from Step 5.

3. Click Add secret for each

Step 8: 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 cloudflared-named.yml [here]
5. Click Commit changes..., add a commit message, then click Commit changes

The workflow file will be saved to .github/workflows/cloudflared-named.yml.

Step 9: Run the Workflow

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

The workflow will start immediately.

Step 10: Configure CodeFull.gs

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

const TUNNEL_SERVER_URL = "https://tunnel.yourdomain.com";
const TUNNEL_AUTH_KEY = "the-secret-you-set-in-step-7";

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

This step is performed only once. The tunnel URL never changes between restarts.

Step 11: Verify

Use mhrv-rs test or visit https://ipleak.net through your proxy. You should see a Cloudflare IP address.

How It Works

1. GitHub Actions starts a Docker container running mhrv-tunnel-node on port 8080
2. cloudflared connects to Cloudflare using the named tunnel credentials
3. Cloudflare routes traffic from your custom domain to the runner through a secure, persistent tunnel
4. CodeFull.gs forwards tunnel operations to your custom domain over HTTPS
5. The runner stays alive for 6 hours, then shuts down automatically
6. On restart, the same domain routes to the new runner — no configuration changes needed

Restarting the Tunnel

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

1. Go to the Actions tab
2. Select Full Tunnel (cloudflared Named)
3. Click Run workflow > Run workflow

That is all — the URL is permanent so CodeFull.gs does not need to be updated.

For automatic restarts every 6 hours, add a schedule trigger to the workflow:

on:
  workflow_dispatch:
  schedule:
    - cron: '0 */6 * * *'

Limitations

• Requires a one-time local setup with cloudflared CLI
• Requires a Cloudflare account with a domain
• 6-hour maximum per session (GitHub Actions limit)

Troubleshooting

Problem	Solution
cloudflared tunnel login fails	Ensure your browser can reach dash.cloudflare.com. You may need to use a proxy or alternative network for this step.
cloudflared tunnel create fails	Verify you are authenticated. Run cloudflared tunnel login again.
Workflow fails at Docker step	GitHub Actions may be pulling the image for the first time. Wait 2-3 minutes and retry.
cloudflared fails to connect	Verify all four secrets are set correctly. Check that CLOUDFLARE_TUNNEL_CREDENTIALS contains valid JSON.
CodeFull.gs returns 502 or timeout	Verify the workflow is still running. Check that TUNNEL_AUTH_KEY matches in both the secret and CodeFull.gs. Ensure the DNS record was created in Step 4.