ngrok

Secure tunnels to expose local servers to the internet. Test webhooks, share demos, and debug integrations instantly.

48 commands

Browse by Topic

Getting Started

Quick setup and installation

3commands

HTTP Tunnels

HTTP/HTTPS tunnels

15commands

TCP Tunnels

TCP tunnels

6commands

TLS Tunnels

TLS termination

5commands

Configuration

ngrok config

10commands

API

Automation

9commands

Install ngrok (macOS)

$ brew install ngrok

Install ngrok using Homebrew on macOS

Add auth token

$ ngrok config add-authtoken <token>

Configure ngrok with your authentication token from dashboard

Expose local port

$ ngrok http 3000

Create a public tunnel to your local port 3000

Basic HTTP tunnel

$ ngrok http 3000

Expose local port 3000 via HTTP.

HTTPS only tunnel

$ ngrok http https://localhost:3000

Tunnel to local HTTPS server.

Custom domain

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

Use custom subdomain (paid feature).

With basic auth

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

Add basic authentication.

Inspect requests

$ ngrok http 3000 --inspect

Enable request inspection at localhost:4040.

Host header rewrite

$ ngrok http --host-header=myapp.local 3000

Rewrite Host header for virtual hosts.

HTTPS scheme only

$ ngrok http --scheme=https 3000

Only listen on HTTPS, disable HTTP.

Enable compression

$ ngrok http --compression 3000

Enable gzip compression for responses.

Circuit breaker

$ ngrok http --circuit-breaker=0.8 3000

Trip circuit breaker at 80% 5xx error rate.

Add request header

$ ngrok http --request-header-add='X-Forwarded-By:ngrok' 3000

Add a custom header to upstream requests.

Add response header

$ ngrok http --response-header-add='X-Frame-Options:DENY' 3000

Add a custom header to responses.

OAuth protection

$ ngrok http --oauth=google --oauth-allow-email=user@example.com 3000

Protect tunnel with Google OAuth.

Webhook verification

$ ngrok http --verify-webhook=github --verify-webhook-secret=SECRET 3000

Verify webhook signatures from a provider.

IP restriction

$ ngrok http --allow-cidr=192.168.1.0/24 --deny-cidr=0.0.0.0/0 3000

Restrict tunnel access by IP range.

Traffic policy file

$ ngrok http --traffic-policy-file=policy.yml 3000

Apply a traffic policy from a YAML file.

TCP tunnel

$ ngrok tcp 22

Expose TCP port (e.g., SSH).

Remote address

$ ngrok tcp --remote-addr=1.tcp.ngrok.io:12345 22

Use specific remote address (paid).

TCP to localhost database

$ ngrok tcp 5432

Expose PostgreSQL for remote access.

TCP tunnel for MySQL

$ ngrok tcp 3306

Expose MySQL for remote access.

TCP tunnel for Redis

$ ngrok tcp 6379

Expose Redis for remote access.

TCP with IP restriction

$ ngrok tcp --allow-cidr=10.0.0.0/8 22

Restrict TCP tunnel access by IP range.

TLS tunnel

$ ngrok tls 443

Create a TLS tunnel with automatic certs.

TLS with custom domain

$ ngrok tls --domain=secure.example.com 443

TLS tunnel on a custom domain.

TLS with custom cert

$ ngrok tls --crt=/path/to/cert.pem --key=/path/to/key.pem 443

Use your own TLS certificate and key.

Mutual TLS

$ ngrok tls --mutual-tls-cas=/path/to/ca.pem 443

Require client certificates for mutual TLS.

TLS terminate at edge

$ ngrok tls --terminate-at=edge 443

Terminate TLS at the ngrok edge, forward plaintext.

Add auth token

$ ngrok config add-authtoken YOUR_TOKEN

Configure ngrok authentication.

Edit config file

$ ngrok config edit

Open ngrok.yml in editor.

Show config path

$ ngrok config check

Verify config file location and syntax.

Start named tunnel

$ ngrok start myapp

Start tunnel defined in config.

Start all tunnels

$ ngrok start --all

Start all tunnels from config.

Select region

$ ngrok http --region=eu 3000

Start tunnel in a specific region (us, eu, ap, au).

Set log level

$ ngrok http --log=stdout --log-level=debug 3000

Enable debug logging to stdout.

Log to file

$ ngrok http --log=ngrok.log --log-format=json 3000

Write JSON-formatted logs to a file.

Start multiple named tunnels

$ ngrok start webapp api worker

Start multiple named tunnels from config.

Diagnose connectivity

$ ngrok diagnose

Run connectivity diagnostics to troubleshoot issues.

List tunnels (API)

$ curl http://localhost:4040/api/tunnels

Get active tunnels via local API.

Get public URL

$ curl -s http://localhost:4040/api/tunnels | jq '.tunnels[0].public_url'

Extract public URL from API.

Stop tunnel (API)

$ curl -X DELETE http://localhost:4040/api/tunnels/command_line

Stop a tunnel via API.

Check version

$ ngrok version

Show ngrok version.

List endpoints

$ ngrok api endpoints list

List all active endpoints via ngrok API.

List reserved domains

$ ngrok api reserved-domains list

List all reserved domains on your account.

Replay captured request

$ curl -X POST http://localhost:4040/api/requests/http/req_abc123/replay

Replay a captured request from the inspector.

Update ngrok

$ ngrok update

Update ngrok to the latest version.

List edge routes

$ ngrok api edges https list

List all HTTPS edges configured in your account.

Discussion

Loading comments...

ngrok

Secure tunnels to expose local servers to the internet. Test webhooks, share demos, and debug integrations instantly.

48 commands

Browse by Topic

Getting Started

Quick setup and installation

3commands

HTTP Tunnels

HTTP/HTTPS tunnels

15commands

TCP Tunnels

TCP tunnels

6commands

TLS Tunnels

TLS termination

5commands

Configuration

ngrok config

10commands

API

Automation

9commands

Install ngrok (macOS)

$ brew install ngrok

Install ngrok using Homebrew on macOS

Add auth token

$ ngrok config add-authtoken <token>

Configure ngrok with your authentication token from dashboard

Expose local port

$ ngrok http 3000

Create a public tunnel to your local port 3000

Basic HTTP tunnel

$ ngrok http 3000

Expose local port 3000 via HTTP.

HTTPS only tunnel

$ ngrok http https://localhost:3000

Tunnel to local HTTPS server.

Custom domain

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

Use custom subdomain (paid feature).

With basic auth

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

Add basic authentication.

Inspect requests

$ ngrok http 3000 --inspect

Enable request inspection at localhost:4040.

Host header rewrite

$ ngrok http --host-header=myapp.local 3000

Rewrite Host header for virtual hosts.

HTTPS scheme only

$ ngrok http --scheme=https 3000

Only listen on HTTPS, disable HTTP.

Enable compression

$ ngrok http --compression 3000

Enable gzip compression for responses.

Circuit breaker

$ ngrok http --circuit-breaker=0.8 3000

Trip circuit breaker at 80% 5xx error rate.

Add request header

$ ngrok http --request-header-add='X-Forwarded-By:ngrok' 3000

Add a custom header to upstream requests.

Add response header

$ ngrok http --response-header-add='X-Frame-Options:DENY' 3000

Add a custom header to responses.

OAuth protection

$ ngrok http --oauth=google --oauth-allow-email=user@example.com 3000

Protect tunnel with Google OAuth.

Webhook verification

$ ngrok http --verify-webhook=github --verify-webhook-secret=SECRET 3000

Verify webhook signatures from a provider.

IP restriction

$ ngrok http --allow-cidr=192.168.1.0/24 --deny-cidr=0.0.0.0/0 3000

Restrict tunnel access by IP range.

Traffic policy file

$ ngrok http --traffic-policy-file=policy.yml 3000

Apply a traffic policy from a YAML file.

TCP tunnel

$ ngrok tcp 22

Expose TCP port (e.g., SSH).

Remote address

$ ngrok tcp --remote-addr=1.tcp.ngrok.io:12345 22

Use specific remote address (paid).

TCP to localhost database

$ ngrok tcp 5432

Expose PostgreSQL for remote access.

TCP tunnel for MySQL

$ ngrok tcp 3306

Expose MySQL for remote access.

TCP tunnel for Redis

$ ngrok tcp 6379

Expose Redis for remote access.

TCP with IP restriction

$ ngrok tcp --allow-cidr=10.0.0.0/8 22

Restrict TCP tunnel access by IP range.

TLS tunnel

$ ngrok tls 443

Create a TLS tunnel with automatic certs.

TLS with custom domain

$ ngrok tls --domain=secure.example.com 443

TLS tunnel on a custom domain.

TLS with custom cert

$ ngrok tls --crt=/path/to/cert.pem --key=/path/to/key.pem 443

Use your own TLS certificate and key.

Mutual TLS

$ ngrok tls --mutual-tls-cas=/path/to/ca.pem 443

Require client certificates for mutual TLS.

TLS terminate at edge

$ ngrok tls --terminate-at=edge 443

Terminate TLS at the ngrok edge, forward plaintext.

Add auth token

$ ngrok config add-authtoken YOUR_TOKEN

Configure ngrok authentication.

Edit config file

$ ngrok config edit

Open ngrok.yml in editor.

Show config path

$ ngrok config check

Verify config file location and syntax.

Start named tunnel

$ ngrok start myapp

Start tunnel defined in config.

Start all tunnels

$ ngrok start --all

Start all tunnels from config.

Select region

$ ngrok http --region=eu 3000

Start tunnel in a specific region (us, eu, ap, au).

Set log level

$ ngrok http --log=stdout --log-level=debug 3000

Enable debug logging to stdout.

Log to file

$ ngrok http --log=ngrok.log --log-format=json 3000

Write JSON-formatted logs to a file.

Start multiple named tunnels

$ ngrok start webapp api worker

Start multiple named tunnels from config.

Diagnose connectivity

$ ngrok diagnose

Run connectivity diagnostics to troubleshoot issues.

List tunnels (API)

$ curl http://localhost:4040/api/tunnels

Get active tunnels via local API.

Get public URL

$ curl -s http://localhost:4040/api/tunnels | jq '.tunnels[0].public_url'

Extract public URL from API.

Stop tunnel (API)

$ curl -X DELETE http://localhost:4040/api/tunnels/command_line

Stop a tunnel via API.

Check version

$ ngrok version

Show ngrok version.

List endpoints

$ ngrok api endpoints list

List all active endpoints via ngrok API.

List reserved domains

$ ngrok api reserved-domains list

List all reserved domains on your account.

Replay captured request

$ curl -X POST http://localhost:4040/api/requests/http/req_abc123/replay

Replay a captured request from the inspector.

Update ngrok

$ ngrok update

Update ngrok to the latest version.

List edge routes

$ ngrok api edges https list

List all HTTPS edges configured in your account.

Discussion

Loading comments...