Skip to main content

Sep 9, 2025

The ngrok cheatsheet

Avatar for Aaishika S Bhattacharya

Aaishika S Bhattacharya

•

1,370 words

•Topics:

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

macOS

1# Install via Homebrew2brew install ngrok3 4# Add your authtoken5ngrok config add-authtoken <token>6 7# Start an endpoint8ngrok http 80

Linux

1# Install via Apt2curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \3  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \4  && echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" \5  | sudo tee /etc/apt/sources.list.d/ngrok.list \6  && sudo apt update \7  && sudo apt install ngrok8# OR9# Install via Snap10snap install ngrok11 12# Add your authtoken13ngrok config add-authtoken <token>14 15# Start an endpoint16ngrok http 80

Windows

1# Install via WinGet2winget install ngrok -s msstore3# OR4# Install via Scoop5scoop install ngrok6 7# Add your authtoken8ngrok config add-authtoken <token>9 10# Start an endpoint11ngrok http 80

Kubernetes

1# Add ngrok Kubernetes Operator to Helm2helm repo add ngrok https://charts.ngrok.com3 4# Add ngrok API key and authtoken5export NGROK_AUTHTOKEN=YOUR_NGROK_AUTHTOKEN6export NGROK_API_KEY=YOUR_NGROK_API_KEY7 8helm install ngrok-operator ngrok/ngrok-operator \9  --namespace ngrok-operator \10  --create-namespace \11  --set credentials.apiKey=$NGROK_API_KEY \12  --set credentials.authtoken=$NGROK_AUTHTOKEN

Docker

1# Install via Docker2docker pull ngrok/ngrok3 4# Run ngrok via Docker5docker run --net=host -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80

SDKs

1# Node.js: https://ngrok.com/downloads/node-js2npm install @ngrok/ngrok3 4# Go: https://ngrok.com/downloads/go5go get golang.ngrok.com/ngrok/v26 7# Python: https://ngrok.com/downloads/python8python3 -m pip install ngrok9 10# Rust: https://ngrok.com/downloads/rust11# Install ngrok-rust package and the required dependencies12cargo 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

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

Web app

1# Example: On localhost:30002ngrok http 3000

SSH server

1# Example: On Port 222ngrok 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

1ngrok diagnose2 3# To test IPv6 connectivity4ngrok diagnose --ipv6 true5 6# To test connectivity between the ngrok agent and all ngrok points of presence7ngrok diagnose --region all8 9# For a verbose report10ngrok diagnose -w out.txt #OR11ngrok 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

1# policy.yaml2on_http_request:3  - actions:4      - type: oauth5        config:6          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

1# policy.yaml2on_http_request:3  - actions:4      - type: oauth5        config:6          provider: google7  - expressions:8      - "!(actions.ngrok.oauth.identity.email in ['alice@example.com','bob@example.com'])"9    actions:10      - type: deny

Restrict OAuth to specific domains

1# policy.yaml2on_http_request:3  - actions:4      - type: oauth5        config:6          provider: google7  - expressions:8      - "!(actions.ngrok.oauth.identity.email.endsWith('@example.com'))"9    actions:10      - type: deny

Verify your webhooks

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

Add the verify-webhook action for Slack

1# policy.yaml2on_http_request:3  - actions:4      - type: verify-webhook5        config:6          provider: slack7          secret: $SLACK_TOKEN

Read more: https://ngrok.com/docs/integrations/webhooks/slack-webhooks

CLI Alternative

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

Replace provider for any supported provider

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

1# policy.yaml2on_http_request:3  - actions:4      - type: verify-webhook5        config:6          provider: $PROVIDER # Example: GitHub7          secret: $PROVIDER_TOKEN

Do even more with internal endpoints

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

Create an internal agent endpoint

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

Create a Cloud Endpoint

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

1# Forward to an internal endpoint from a public endpoint2on_http_request:3  - actions:4      - type: forward-internal5        config:6          url: https://api.internal

Manage traffic in other ways

Add path-based routing

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

1# policy.yaml2# Route /api/* to api.internal, /app/* to app.internal3on_http_request:4  - expressions:5      - "req.path.startsWith('/api/')"6    actions:7      - type: forward-internal8        config:9          url: https://api.internal10  - expressions:11      - "req.path.startsWith('/app/')"12    actions:13      - type: forward-internal14        config:15          url: https://app.internal

Route traffic by anything

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

1# policy.yaml2# Host-based and header-based dynamic forwarding to internal endpoints via forward-internal action3on_http_request:4  - expressions:5      - "req.host == 'api.example.com'"6    actions:7      - type: forward-internal8        config: { url: https://api.internal }9  - expressions:10      - "getReqHeader('X-Tenant') != ''"11    actions:12      - type: forward-internal13        config: { url: https://tenant.internal }

Multiplex to internal services from a single domain

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

1# policy.yaml2on_http_request:3  - actions:4      - type: forward-internal5        config:6          url: https://${req.host.split(".$NGROK_DOMAIN")[0]}.internal

Add rate limiting

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

1# policy.yaml2# 10 requests per 60s window per client IP -> 429 on limit3on_http_request:4  - actions:5      - type: rate-limit6        config:7          name: per-ip-60s8          algorithm: sliding_window9          capacity: 1010          rate: "60s"11          bucket_key:12            - 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

1# policy.yaml2# Send a robots.txt denying crawlers3on_http_request:4  - expressions:5      - "req.path == '/robots.txt'"6    actions:7      - type: custom-response8        config:9          status_code: 20010          headers:11            Content-Type: "text/plain"12          body: |13            User-agent: *14            Disallow: /
1# policy.yaml2# Deny common bot/AI user agents3on_http_request:4  - expressions:5      - "req.user_agent.raw.matches('(?i)(gptbot|chatgpt-user|ccbot|bingbot|googlebot)')"6    actions:7      - type: deny
1# policy.yaml2# Also add X-Robots-Tag to all responses3on_http_response:4  - actions:5      - type: add-headers6        config:7          headers:8            X-Robots-Tag: "noindex, nofollow, noai, noimageai"

Add headers

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

Via CLI

1# Common security headers2ngrok http 8080 \3  --request-header-add "X-Frame-Options: DENY" \4  --response-header-add "Referrer-Policy: no-referrer"

Via Traffic Policy

1# policy.yaml2# Add headers on request/response3on_http_request:4  - actions:5      - type: add-headers6        config:7          headers:8            X-Frame-Options: "DENY"9on_http_response:10  - actions:11      - type: add-headers12        config:13          headers:14            Referrer-Policy: "no-referrer"

Restrict access by IPs

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

1# Allow only 203.0.113.0/24; deny others2ngrok http 8080 --cidr-allow 203.0.113.0/243 4# Or explicitly deny CIDRs5ngrok 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/

1# policy.yaml2# Apply OWASP Core Rule Set on requests/responses3on_http_request:4  - actions:5      - type: owasp-crs-request6on_http_response:7  - actions:8      - type: owasp-crs-response

CLI Flags

url

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

traffic-policy-file

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

traffic-policy-url

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

pooling-enabled

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

What else can I do with ngrok?

Ending notes

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