The ngrok cheatsheet

•

Sep 9, 2025

•

1127 words

Getting started with ngrok is almost suspiciously easy. Which is why the question we hear most often isn’t "where do I start?" but rather “what else can I do with ngrok?” For over a decade, we’ve been serving millions of developers and, through them, millions of users.

Sure, our documentation has all the answers, every CLI flag, every Traffic Policy configuration neatly laid out, but what about the developers who are always on the lookout for a TL;DR? What if you too are not looking for a full solution or a specific use case for your next project, but just want to know… what else **you** can do with ngrok?

Presenting ngrok's new cheatsheet that walks you through some of our most interesting offerings, designed to scratch that itch of not just serving, but also securing endpoints in as little as two steps. Read on or download the crisp two-pager printable in PDF.

Installation

Sign up for a free account: https://ngrok.com/signup
Keep your authtoken handy: https://dashboard.ngrok.com/get-started/your-authtoken

macOS

# Install via Homebrew
brew install ngrok

# Add your authtoken
ngrok config add-authtoken <token>

# Start an endpoint
ngrok http 80

Linux

# Install via Apt
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 bookworm main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update \
  && sudo apt install ngrok
# OR
# Install via Snap
snap install ngrok

# Add your authtoken
ngrok config add-authtoken <token>

# Start an endpoint
ngrok http 80

Windows

# Install via WinGet
winget install ngrok -s msstore
# OR
# Install via Scoop
scoop install ngrok

# Add your authtoken
ngrok config add-authtoken <token>

# Start an endpoint
ngrok http 80

Kubernetes

# Add ngrok Kubernetes Operator to Helm
helm repo add ngrok https://charts.ngrok.com

# Add ngrok API key and authtoken
export NGROK_AUTHTOKEN=YOUR_NGROK_AUTHTOKEN
export NGROK_API_KEY=YOUR_NGROK_API_KEY

helm install ngrok-operator ngrok/ngrok-operator \
  --namespace ngrok-operator \
  --create-namespace \
  --set credentials.apiKey=$NGROK_API_KEY \
  --set credentials.authtoken=$NGROK_AUTHTOKEN

Docker

# Install via Docker
docker pull ngrok/ngrok

# Run ngrok via Docker
docker run --net=host -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80

SDKs

# Node.js: https://ngrok.com/downloads/node-js
npm install @ngrok/ngrok

# Go: https://ngrok.com/downloads/go
go get golang.ngrok.com/ngrok/v2

# Python: https://ngrok.com/downloads/python
python3 -m pip install ngrok

# Rust: https://ngrok.com/downloads/rust
# Install ngrok-rust package and the required dependencies
cargo add ngrok -F axum && cargo add axum && cargo add tokio -F rt-multi-thread -F macros

Expose different kinds of servers

Read the Docs: https://ngrok.com/docs/agent/#example-usage

API service

# Example: API service on localhost:8080
ngrok http 8080

Web app

# Example: On localhost:3000
ngrok http 3000

SSH server

# Example: On Port 22
ngrok tcp 22

Postgres server

ngrok tcp 5432

Any service or server on a different machine

ngrok http http://192.168.1.50:8080

Troubleshoot

Read the Docs: https://ngrok.com/docs/agent/#troubleshooting-connectivity

ngrok diagnose

# To test IPv6 connectivity
ngrok diagnose --ipv6 true

# To test connectivity between the ngrok agent and all ngrok points of presence
ngrok diagnose --region all

# For a verbose report
ngrok diagnose -w out.txt #OR
ngrok diagnose --write-report out.txt

Add authentication with Traffic Policy

Read the Docs: https://ngrok.com/docs/traffic-policy/

Create a Traffic Policy file `policy.yaml`

nano policy.yaml

Add the OAuth Action with Google

List of Providers: https://ngrok.com/docs/traffic-policy/actions/oauth/#supported-providers

# policy.yaml
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google # OAuth available with Amazon, Facebook, GitHub, GitLab, Google, LinkedIn, Microsoft, Twitch

Run your endpoint with the Traffic Policy file

ngrok http 8080 --traffic-policy-file=policy.yaml

Restrict OAuth to specific emails

# policy.yaml
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
  - expressions:
      - "!(actions.ngrok.oauth.identity.email in ['alice@example.com','bob@example.com'])"
    actions:
      - type: deny

Restrict OAuth to specific domains

# policy.yaml
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
  - expressions:
      - "!(actions.ngrok.oauth.identity.email.endsWith('@example.com'))"
    actions:
      - type: deny

Verify your webhooks

Read the Docs: https://ngrok.com/docs/traffic-policy/actions/verify-webhook/

Add the `verify-webhook` action for Slack

# policy.yaml
on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: slack
          secret: $SLACK_TOKEN

CLI Alternative

ngrok http 3000 \
  --verify-webhook=slack \
  --verify-webhook-secret=$SLACK_TOKEN

Replace `provider` for any supported provider

List of supported providers: https://ngrok.com/docs/traffic-policy/actions/verify-webhook/

# policy.yaml
on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: $PROVIDER # Example: GitHub
          secret: $PROVIDER_TOKEN

Do even more with internal endpoints

Read the docs: https://ngrok.com/docs/universal-gateway/internal-endpoints/

Create an internal agent endpoint

# Create a private, internal agent endpoint only reachable via forward-internal
ngrok http 8080 --url https://api.internal

Create a Cloud Endpoint

Read the Docs: https://ngrok.com/docs/traffic-policy/actions/forward-internal/

Create a new Cloud Endpoint in your ngrok Dashboard
Enter a static URL you've reserved
Click Create Cloud Endpoint
Replace the default Traffic Policy with the following:

# Forward to an internal endpoint from a public endpoint
on_http_request:
  - actions:
      - type: forward-internal
        config:
          url: https://api.internal

Manage traffic in other ways

Add path-based routing

Read the Docs: https://ngrok.com/docs/universal-gateway/cloud-endpoints/routing-and-policy-decentralization/

# policy.yaml
# Route /api/* to api.internal, /app/* to app.internal
on_http_request:
  - expressions:
      - "req.path.startsWith('/api/')"
    actions:
      - type: forward-internal
        config:
          url: https://api.internal
  - expressions:
      - "req.path.startsWith('/app/')"
    actions:
      - type: forward-internal
        config:
          url: https://app.internal

Route traffic by anything

Read the Docs: https://ngrok.com/docs/traffic-policy/actions/forward-internal/#examples

# policy.yaml
# Host-based and header-based dynamic forwarding to internal endpoints via forward-internal action
on_http_request:
  - expressions:
      - "req.host == 'api.example.com'"
    actions:
      - type: forward-internal
        config: { url: https://api.internal }
  - expressions:
      - "getReqHeader('X-Tenant') != ''"
    actions:
      - type: forward-internal
        config: { url: https://tenant.internal }

Multiplex to internal services from a single domain

Read the Docs: https://ngrok.com/docs/universal-gateway/examples/multiplex/

# policy.yaml
on_http_request:
  - actions:
      - type: forward-internal
        config:
          url: https://${req.host.split(".$NGROK_DOMAIN")[0]}.internal

Add rate limiting

Read the Docs: https://ngrok.com/docs/traffic-policy/actions/rate-limit/

# policy.yaml
# 10 requests per 60s window per client IP -> 429 on limit
on_http_request:
  - actions:
      - type: rate-limit
        config:
          name: per-ip-60s
          algorithm: sliding_window
          capacity: 10
          rate: "60s"
          bucket_key:
            - conn.client_ip

Block search and AI bots

Read the Docs: https://ngrok.com/docs/traffic-policy/examples/block-unwanted-requests/#how-do-i-deny-traffic-from-bots-and-crawlers-with-a-robotstxt

# policy.yaml
# Send a robots.txt denying crawlers
on_http_request:
  - expressions:
      - "req.path == '/robots.txt'"
    actions:
      - type: custom-response
        config:
          status_code: 200
          headers:
            Content-Type: "text/plain"
          body: |
            User-agent: *
            Disallow: /

# policy.yaml
# Deny common bot/AI user agents
on_http_request:
  - expressions:
      - "req.user_agent.raw.matches('(?i)(gptbot|chatgpt-user|ccbot|bingbot|googlebot)')"
    actions:
      - type: deny

# policy.yaml
# Also add X-Robots-Tag to all responses
on_http_response:
  - actions:
      - type: add-headers
        config:
          headers:
            X-Robots-Tag: "noindex, nofollow, noai, noimageai"

Add headers

Read the Docs: https://ngrok.com/docs/traffic-policy/actions/add-headers/

Via CLI

# Common security headers
ngrok http 8080 \
  --request-header-add "X-Frame-Options: DENY" \
  --response-header-add "Referrer-Policy: no-referrer"

Via Traffic Policy

# policy.yaml
# Add headers on request/response
on_http_request:
  - actions:
      - type: add-headers
        config:
          headers:
            X-Frame-Options: "DENY"
on_http_response:
  - actions:
      - type: add-headers
        config:
          headers:
            Referrer-Policy: "no-referrer"

Restrict access by IPs

Read the Docs: https://ngrok.com/docs/traffic-policy/actions/restrict-ips/

# Allow only 203.0.113.0/24; deny others
ngrok http 8080 --cidr-allow 203.0.113.0/24

# Or explicitly deny CIDRs
ngrok http 8080 --cidr-deny 0.0.0.0/0

Block all the potentially bad things

Read the Docs: https://ngrok.com/docs/traffic-policy/actions/owasp-crs-response/

# policy.yaml
# Apply OWASP Core Rule Set on requests/responses
on_http_request:
  - actions:
      - type: owasp-crs-request
on_http_response:
  - actions:
      - type: owasp-crs-response

CLI Flags

`url`

# Choose a URL instead of random assignment
ngrok http 8080 --url https://baz.ngrok.dev

`traffic-policy-file`

# Manipulate traffic to your endpoint with a traffic policy file
ngrok http 8080 --url https://baz.ngrok.dev --traffic-policy-file policy.yaml

`traffic-policy-url`

# Manipulate traffic to your endpoint with a traffic policy URL
ngrok http 8080 --url https://baz.ngrok.dev policy --traffic-policy-url https://example.com/policy.yml

`pooling-enabled`

# Load Balance (different ports)
ngrok http 8080 --url https://api.example.com --pooling-enabled
ngrok http 8081 --url https://api.example.com --pooling-enabled

What else can I do with ngrok?

Use the ngrok Kubernetes Operator: https://ngrok.com/docs/k8s/
Get started with traffic observability: https://ngrok.com/docs/obs/
Read ngrok's security best practices: https://ngrok.com/docs/guides/security-dev-productivity/
Check out the gateway Examples Gallery: https://ngrok.com/docs/universal-gateway/examples/

Ending notes

The first iteration of the ngrok cheat sheet was created by Keith Casey, who served on the Product/GTM Team at ngrok.

Installation

macOS

Linux

Windows

Kubernetes

Docker

SDKs

Expose different kinds of servers

API service

Web app

SSH server

Postgres server

Any service or server on a different machine

Troubleshoot

Add authentication with Traffic Policy

Create a Traffic Policy file policy.yaml

Add the OAuth Action with Google

Run your endpoint with the Traffic Policy file

Restrict OAuth to specific emails

Restrict OAuth to specific domains

Verify your webhooks

Add the verify-webhook action for Slack

CLI Alternative

Replace provider for any supported provider

Do even more with internal endpoints

Create an internal agent endpoint

Create a Cloud Endpoint

Manage traffic in other ways

Add path-based routing

Route traffic by anything

Multiplex to internal services from a single domain

Add rate limiting

Block search and AI bots

Add headers

Via CLI

Via Traffic Policy

Restrict access by IPs

Block all the potentially bad things

CLI Flags

url

traffic-policy-file

traffic-policy-url

pooling-enabled

What else can I do with ngrok?

Ending notes

Installation

macOS

Linux

Windows

Kubernetes

Docker

SDKs

Expose different kinds of servers

API service

Web app

SSH server

Postgres server

Any service or server on a different machine

Troubleshoot

Add authentication with Traffic Policy

Create a Traffic Policy file policy.yaml

Add the OAuth Action with Google

Run your endpoint with the Traffic Policy file

Restrict OAuth to specific emails

Restrict OAuth to specific domains

Verify your webhooks

Add the verify-webhook action for Slack

CLI Alternative

Replace provider for any supported provider

Do even more with internal endpoints

Create an internal agent endpoint

Create a Cloud Endpoint

Manage traffic in other ways

Add path-based routing

Route traffic by anything

Multiplex to internal services from a single domain

Add rate limiting

Block search and AI bots

Add headers

Via CLI

Create a Traffic Policy file `policy.yaml`

Add the `verify-webhook` action for Slack

Replace `provider` for any supported provider

`url`

`traffic-policy-file`

`traffic-policy-url`

`pooling-enabled`

Create a Traffic Policy file `policy.yaml`

Add the `verify-webhook` action for Slack

Replace `provider` for any supported provider

`url`

`traffic-policy-file`

`traffic-policy-url`

`pooling-enabled`