Skip to main content

​
Overview

The tunnel command creates a secure Cloudflare tunnel that exposes a local port to the internet. It automatically generates a public URL and displays a QR code for easy sharing.

​
Syntax

ahh tunnel --port <port>

​
Parameters

​
port
number
required
The local port number to tunnel. This is the port where your local service is running.Aliases: -p

​
Usage Examples

# Tunnel port 3000 to the internet
ahh tunnel --port 3000

​
Output

When successful, the command displays:
  • A spinner message: “Starting tunnel, this may take a second…”
  • The tunnel URL (e.g., https://xyz-abc.trycloudflare.com)
  • A QR code containing the tunnel URL for easy mobile access
Example Output
Starting tunnel, this may take a second...
Tunnel URL: https://random-subdomain.trycloudflare.com
[QR CODE]

​
Return Value

The underlying tunnel() function returns an object with:
  • url: The public tunnel URL (string)
  • kill: Function to terminate the tunnel process
If the tunnel fails to create, it returns an empty object {}.

​
Error Handling

Rate Limiting: Cloudflare may rate limit free tunnel creation. If you encounter rate limits, consider configuring a tunnel on your own domain.
The command handles the following errors:

​
Rate Limit Error

If you see “429 Too Many Requests”, the command will display: 
Rate limited creating free tunnel. Configure a tunnel on your domain to avoid rate limits.

​
Connection Failures

The tunnel monitors the Cloudflare process output for:
  • Invalid character errors
  • Connection registration success
  • Rate limit responses

​
Technical Details

​
Implementation

The tunnel command uses Cloudflare’s cloudflared binary to create a quick tunnel. The implementation:
  1. Spawns a cloudflared tunnel --url http://localhost:<port> process
  2. Monitors the stderr output for the tunnel URL
  3. Extracts the URL using regex: /https:\/\/[a-zA-Z0-9-]+\.trycloudflare\.com/
  4. Waits for “Registered tunnel connection” confirmation
  5. Returns the URL and process control

​
URL Pattern

Cloudflare generates URLs matching the pattern: 
https://[random-subdomain].trycloudflare.com

​
Notes

The tunnel process runs in the background and continues until you terminate the CLI. The tunnel will close when you exit the process.
Ensure cloudflared is installed on your system. The Ahh CLI requires this dependency to create tunnels.
  • serve - Serve files from the current directory with automatic tunneling
  • webhook - Start a webhook server with tunneling
  • qr - Generate QR codes for URLs

Build docs developers (and LLMs) love

Get started for freeTalk to us