ngrok Tunnel Tool

ngrok cheatsheet — expose localhost to internet for webhooks and demos. ngrok http 3000, ngrok tcp 22, ngrok http --subdomain. Inspect traffic at localhost:4040.

6 min read

What it is

ngrok is a tool that creates secure tunnels from a public endpoint into your local development machine, allowing you to expose local servers to the internet. It’s useful for testing webhooks, sharing local demos, and debugging services that need to receive external requests.

Installation

Linux

curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
&& echo "deb https://ngrok-agent.s3.amazonaws.com/deb stable main" | sudo tee /etc/apt/sources.list.d/ngrok.list \
&& sudo apt update \
&& sudo apt install ngrok

Mac

brew install --cask ngrok

Or download the binary from ngrok.com and place it in your PATH.

Windows

Download the ngrok executable from ngrok.com and add its directory to your system’s PATH environment variable.

After installation, you’ll want to connect your account to authenticate your agent.

ngrok config add-authtoken YOUR_AUTHTOKEN

Replace YOUR_AUTHTOKEN with your authtoken found in your ngrok dashboard.

Core Concepts

  • Tunnels: A connection between a public ngrok endpoint (e.g., https://random.ngrok.io) and a local service running on your machine.
  • Public Endpoint: The URL provided by ngrok that is accessible from the internet.
  • Local Service: The application or server running on your machine that you want to expose.
  • ngrok Agent: The executable you run on your local machine that establishes and manages the tunnel.

Commands / Usage

Starting Tunnels

HTTP Tunnel

Expose a local HTTP server running on port 3000.

ngrok http 3000
  • Starts an HTTP tunnel to localhost:3000. ngrok will print a public forwarding URL (e.g., http://random.ngrok.io) and a TLS URL (e.g., https://random.ngrok.io).

HTTPS Tunnel

Expose a local HTTPS server running on port 8443.

ngrok http --scheme=https 8443
  • Starts an HTTPS tunnel to localhost:8443. It will use TLS for the local connection.

TCP Tunnel

Expose a local TCP service running on port 22 (e.g., SSH).

ngrok tcp 22
  • Starts a TCP tunnel to localhost:22. ngrok will print a public forwarding address (e.g., tcp://0.tcp.ngrok.io:12345).

TLS Tunnel (Custom Domain)

Expose a local service using a custom TLS certificate.

ngrok tls --domain=your.custom.domain.com 443
  • Starts a TLS tunnel to localhost:443 for the specified custom domain. This requires domain verification in your ngrok dashboard.

Reserved Domains

Start a tunnel using a previously reserved domain name.

ngrok http --domain=my-awesome-app.ngrok.io 8080
  • Starts an HTTP tunnel to localhost:8080 using the reserved domain my-awesome-app.ngrok.io.

Basic Authentication

Add basic authentication to your tunnel.

ngrok http --basic-auth="user:password" 80
  • Protects the tunnel with basic authentication using the provided username and password.

Custom Tunnel Name

Assign a name to your tunnel for easier identification in the dashboard.

ngrok http --label=subdomain=my-api --label=env=dev 5000
  • Starts an HTTP tunnel to localhost:5000 and labels it with subdomain=my-api and env=dev.

Tunneling to a Specific Host

Tunnel to a service running on a different host on your local network.

ngrok http --host-header=rewrite localhost:8000
  • Exposes localhost:8000 but rewrites the Host header to localhost:8000 for requests arriving at the public ngrok endpoint.

Managing Tunnels

List Active Tunnels

View currently running tunnels.

ngrok tunnels
  • Shows a list of active tunnels, their public addresses, and the local addresses they connect to.

Stop a Tunnel

Use the UI to stop tunnels. Ctrl+C in the terminal where ngrok is running will also stop it.

Inspecting Traffic

Web UI

When ngrok is running, it typically starts a web UI on port 4040.

http://localhost:4040
  • Access this URL in your browser to inspect incoming requests and responses in real-time, replay requests, and view tunnel details.

Inspection Commands

View traffic inspection details.

ngrok inspect http
  • Shows details about the active HTTP tunnel, including inspection URLs and request/response logs.

Configuration

Show Configuration File

Display the current ngrok configuration.

ngrok config show
  • Prints the contents of the ngrok configuration file (usually ~/.config/ngrok/ngrok.yml).

Edit Configuration File

Open the ngrok configuration file in your default editor.

ngrok config edit
  • Allows you to modify settings like authtoken, default regions, and other preferences.

Add Authtoken

Add your authentication token to the configuration.

ngrok config add-authtoken YOUR_AUTH_TOKEN
  • Authenticates your ngrok agent with your ngrok account.

Other Commands

Version

Display the ngrok version.

ngrok version

Help

Display general help or help for a specific command.

ngrok help
ngrok http help

Common Patterns

Exposing a local web server for testing webhooks

If your application receives webhooks on http://localhost:5000, you can expose it like this:

ngrok http 5000

Then, configure your webhook provider to send requests to the https://<your-random-subdomain>.ngrok.io URL provided by ngrok.

Sharing a local demo with a colleague

If you have a local web application running on port 8080, share it:

ngrok http 8080

Copy the public URL and send it to your colleague.

Testing mobile apps that need to hit a local backend

If your mobile app’s backend is running on localhost:3000 on your development machine, and your phone is on the same Wi-Fi network:

ngrok http 3000

Get the public URL (e.g., https://random.ngrok.io). On your mobile device, configure your app or network settings to use random.ngrok.io instead of localhost.

Debugging an API locally

Expose your API running on port 5001 to the internet:

ngrok http 5001

Now you can send requests from external services to this ngrok URL for debugging.

Tunneling to a specific IP and port

If your service is running on 192.168.1.100:8080:

ngrok http --host-header=192.168.1.100:8080 192.168.1.100:8080

Using reserved domains with specific subdomains

If you have reserved my-app.ngrok.io:

ngrok http --domain=my-app.ngrok.io 80

Gotchas

  • Default Ports: ngrok will complain if you try to start a tunnel on a port that is already in use by another ngrok process.
  • Authentication: Without an authtoken, tunnels are temporary and might have stricter rate limits. Always configure your authtoken for a better experience.
  • Localhost vs. Other Hosts: When tunneling to localhost, ngrok by default assumes the request is for localhost. If you are tunneling to a different IP address (e.g., 192.168.1.50:80), you might need to use the --host-header option to specify the correct host header for your local service.
  • HTTPS Locally: If your local service is HTTPS, use --scheme=https to tell ngrok to connect to your local server using TLS. Otherwise, it will attempt an HTTP connection.
  • Traffic Inspection: The inspection UI at localhost:4040 only shows traffic for the current ngrok session. If you restart ngrok, you’ll get a new inspection URL and lose the history.
  • Free Tier Limitations: The free tier has limitations on the number of simultaneous tunnels, custom subdomains, and request lengths. Paid plans offer more features.
  • Firewall Issues: Ensure your local firewall is not blocking ngrok from connecting to your local service.