Named Tunnels

By default, Termbridge uses Cloudflare's account-less Quick Tunnels (trycloudflare.com). These are convenient but can be rate-limited with heavy use.

If you use Termbridge frequently, set up a named tunnel with your Cloudflare account.

Why use a named tunnel?

No rate limits: Quick Tunnels can return 429 errors under heavy use
Consistent URL: Get a stable subdomain instead of random strings
Custom domain: Use your own domain like term.example.com
Better reliability: Named tunnels are more stable for long sessions

Setup

1. Create a Cloudflare account

2. Create a tunnel in Zero Trust

Go to Cloudflare Zero Trust
Navigate to Networks → Tunnels
Click Create a tunnel
Choose Cloudflared as the connector
Name your tunnel (e.g., termbridge)
Copy the tunnel token

3. Add a public hostname

In the tunnel settings, go to Public Hostname
Add a hostname that points to http://localhost:8080 (or your chosen port)
Use a subdomain like term.example.com

4. Run Termbridge with your token

termbridge --port 8080 --tunnel-token <TOKEN> --tunnel-url https://term.example.com

Or use environment variables:

export TERMBRIDGE_TUNNEL_TOKEN=<TOKEN>
export TERMBRIDGE_TUNNEL_URL=https://term.example.com

termbridge --port 8080

The --port flag is required with named tunnels because the hostname is configured to point to a specific port.

Configuration options

Flag	Environment Variable	Description
`--port <port>`	-	Local port (required with named tunnels)
`--tunnel-token <token>`	`TERMBRIDGE_TUNNEL_TOKEN`	Your tunnel token
`--tunnel-url <url>`	`TERMBRIDGE_TUNNEL_URL`	Your public hostname URL

Disabling the tunnel entirely

If you have your own reverse proxy or public URL:

termbridge --no-tunnel --public-url https://your-server.com

Or:

export TERMBRIDGE_TUNNEL=none
export TERMBRIDGE_PUBLIC_URL=https://your-server.com

termbridge

Termbridge will skip starting a tunnel and use your provided URL for the QR code.

Troubleshooting

"429 Too Many Requests"

This means Quick Tunnels are rate-limited. Solutions:

Wait a few minutes and retry
Kill any stale cloudflared processes: pkill cloudflared
Switch to a named tunnel (recommended)

Tunnel starts but URL doesn't work

Verify the hostname in Cloudflare matches --tunnel-url
Check that the port in Cloudflare matches --port
Ensure cloudflared is up to date: cloudflared update

Named tunnel won't connect

Verify your token is correct
Check Cloudflare Zero Trust dashboard for errors
Try running cloudflared tunnel run <TOKEN> directly to see error messages

On this page