Sep 9, 2025

The ngrok cheatsheet

•

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

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

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/gateway/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/gateway/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/gateway/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/gateway/traffic-policy/actions/oauth/#supported-providers

1# policy.yaml2on_http_request:⋯3  - actions:⋯4      - type: oauth⋯5        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: oauth⋯5        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: oauth⋯5        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/gateway/traffic-policy/actions/verify-webhook/

Add the `verify-webhook` action for Slack

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

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/gateway/traffic-policy/actions/verify-webhook/

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

Do even more with internal endpoints

Read the docs: https://ngrok.com/docs/gateway/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/gateway/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:

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

Manage traffic in other ways

Add path-based routing

Read the Docs: https://ngrok.com/docs/gateway/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-internal⋯8        config:⋯9          url: https://api.internal10  - expressions:⋯11      - "req.path.startsWith('/app/')"12    actions:⋯13      - type: forward-internal⋯14        config:⋯15          url: https://app.internal

Route traffic by anything

Read the Docs: https://ngrok.com/docs/gateway/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-internal⋯8        config: { url: https://api.internal }9  - expressions:⋯10      - "getReqHeader('X-Tenant') != ''"11    actions:⋯12      - type: forward-internal⋯13        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-internal⋯5        config:⋯6          url: https://${req.host.split(".$NGROK_DOMAIN")[0]}.internal

Add rate limiting

Read the Docs: https://ngrok.com/docs/gateway/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-limit⋯6        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/gateway/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-response⋯8        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-headers⋯6        config:⋯7          headers:⋯8            X-Robots-Tag: "noindex, nofollow, noai, noimageai"

Add headers

Read the Docs: https://ngrok.com/docs/gateway/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-headers⋯6        config:⋯7          headers:⋯8            X-Frame-Options: "DENY"9on_http_response:⋯10  - actions:⋯11      - type: add-headers⋯12        config:⋯13          headers:⋯14            Referrer-Policy: "no-referrer"

Restrict access by IPs

Read the Docs: https://ngrok.com/docs/gateway/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/gateway/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?

Use the ngrok Kubernetes Operator: https://ngrok.com/docs/gateway/k8s/
Get started with traffic observability: https://ngrok.com/docs/obs/
Read ngrok’s security best practices: https://ngrok.com/docs/gateway/security-dev-productivity/
Check out the gateway Examples Gallery: https://ngrok.com/docs/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.