Getting Started Guide

How to Install and Use ngrok

This guide covers installing ngrok and using it to expose local services to the internet for testing, webhooks, and demonstrations.

Prerequisites

-A free ngrok account (sign up at ngrok.com)

Official Documentation

Install and Authenticate

Install ngrok and add your auth token.

macOS

brew install ngrok

Linux

curl -sSL 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 buster main' | sudo tee /etc/apt/sources.list.d/ngrok.list && sudo apt update && sudo apt install ngrok

Add auth token

ngrok config add-authtoken YOUR_TOKEN_HERE

Expose a Local Web Server

Create a public URL that tunnels to a local port.

HTTP tunnel

ngrok http 3000

With custom domain (paid)

ngrok http --domain=myapp.ngrok.dev 3000

Example output

Session Status: online
Forwarding: https://abc123.ngrok-free.app -> http://localhost:3000

Note: The forwarding URL is publicly accessible. Anyone with the URL can reach your local server. The URL changes each time unless you have a paid plan with reserved domains.

Expose Other Protocols

ngrok supports TCP tunnels for SSH, databases, and other non-HTTP services.

TCP tunnel (SSH)

ngrok tcp 22

TLS tunnel

ngrok tls 443

Inspect Traffic

ngrok's built-in inspector shows all requests passing through the tunnel.

Web inspector

# Visit http://localhost:4040 while ngrok is running
# See all requests, headers, bodies, and responses
# Replay requests to test changes

Note: The traffic inspector at localhost:4040 is incredibly useful for debugging webhooks. You can see exactly what the remote service is sending and replay requests without triggering the webhook again.

Security Considerations

ngrok is a dual-use tool. Understand the risks.

Add basic auth

ngrok http 3000 --basic-auth='user:password'

IP restrictions

ngrok http 3000 --cidr-allow=1.2.3.4/32

Note: ngrok tunnels bypass firewalls and NAT by design. In a corporate environment, outbound ngrok connections may violate security policy. Defenders should monitor for ngrok domains in DNS logs.

Back to ngrok Full Documentation