ngrok cheat sheet: CLI commands, Traffic Policy and more

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 (opens in a new tab) 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 PDF format (opens in a new tab), or a crisp two-pager printable (opens in a new tab).

Installation (opens in a new tab)

Sign up for a free account: https://ngrok.com/signup (opens in a new tab)
Keep your authtoken handy: https://dashboard.ngrok.com/get-started/your-authtoken (opens in a new tab)

macOS (opens in a new tab)

Bash
# Install via Homebrewbrew install ngrok # Add your authtokenngrok config add-authtoken <token> # Start an endpointngrok http 80

Linux (opens in a new tab)

Bash
# Install via Aptcurl -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 Snapsnap install ngrok # Add your authtokenngrok config add-authtoken <token> # Start an endpointngrok http 80

Windows (opens in a new tab)

Bash
# Install via WinGetwinget install ngrok -s msstore# OR# Install via Scoopscoop install ngrok # Add your authtokenngrok config add-authtoken <token> # Start an endpointngrok http 80

Kubernetes (opens in a new tab)

Bash
# Add ngrok Kubernetes Operator to Helmhelm repo add ngrok https://charts.ngrok.com # Add ngrok API key and authtokenexport NGROK_AUTHTOKEN=YOUR_NGROK_AUTHTOKENexport 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 (opens in a new tab)

Bash
# Install via Dockerdocker pull ngrok/ngrok # Run ngrok via Dockerdocker run --net=host -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80

SDKs (opens in a new tab)

Bash
# Node.js: https://ngrok.com/downloads/node-jsnpm install @ngrok/ngrok # Go: https://ngrok.com/downloads/gogo get golang.ngrok.com/ngrok/v2 # Python: https://ngrok.com/downloads/pythonpython3 -m pip install ngrok # Rust: https://ngrok.com/downloads/rust# Install ngrok-rust package and the required dependenciescargo add ngrok -F axum && cargo add axum && cargo add tokio -F rt-multi-thread -F macros

Expose different kinds of servers (opens in a new tab)

API service

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

Web app

Bash
# Example: On localhost:3000ngrok http 3000

SSH server

Bash
# Example: On Port 22ngrok tcp 22

Postgres server

Bash
ngrok tcp 5432

Any service or server on a different machine

Bash
ngrok http http://192.168.1.50:8080

Troubleshoot (opens in a new tab)

Bash
ngrok diagnose # To test IPv6 connectivityngrok diagnose --ipv6 true # To test connectivity between the ngrok agent and all ngrok points of presencengrok diagnose --region all # For a verbose reportngrok diagnose -w out.txt #ORngrok diagnose --write-report out.txt

Add Authentication with Traffic Policy (opens in a new tab)

Create a Traffic Policy file `policy.yaml` (opens in a new tab)

Bash

nano policy.yaml

Add the OAuth Action with Google (opens in a new tab)

List of Providers: https://ngrok.com/docs/traffic-policy/actions/oauth/#supported-providers (opens in a new tab)

YAML
# policy.yamlon_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 (opens in a new tab)

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

Restrict OAuth to specific emails

YAML
# policy.yamlon_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

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

Verify your webhooks (opens in a new tab)

Add the `verify-webhook` action for Slack (opens in a new tab)

YAML
# policy.yamlon_http_request:  - actions:      - type: verify-webhook        config:          provider: slack          secret: $SLACK_TOKEN

CLI Alternative

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

Replace `provider` for any supported provider (opens in a new tab)

List of Supported Providers: https://ngrok.com/docs/traffic-policy/actions/verify-webhook/ (opens in a new tab)

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

Do even more with internal endpoints (opens in a new tab)

Create a Cloud Endpoint (opens in a new tab)

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

Example Traffic Policy File

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

Start Public Endpoint with `forward-internal` action

Bash
ngrok http 8080 --url forward-internal-example.ngrok.app --traffic-policy-file policy.yml

Manage traffic in other ways

Add path-based routing (opens in a new tab)

YAML
# policy.yaml# Route /api/* to api.internal, /app/* to app.internalon_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 (opens in a new tab)

YAML
# policy.yaml# Host-based and header-based dynamic forwarding to internal endpoints via forward-internal actionon_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 (opens in a new tab)

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

Add rate limiting (opens in a new tab)

YAML
# policy.yaml# 10 requests per 60s window per client IP -> 429 on limiton_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 (opens in a new tab)

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

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

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

Add headers (opens in a new tab)

Via CLI

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

Via Traffic Policy

YAML
# policy.yaml# Add headers on request/responseon_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 (opens in a new tab)

Bash
# Allow only 203.0.113.0/24; deny othersngrok http 8080 --cidr-allow 203.0.113.0/24 # Or explicitly deny CIDRsngrok http 8080 --cidr-deny 0.0.0.0/0

Block all the potentially bad things (opens in a new tab)

YAML
# policy.yaml# Apply OWASP Core Rule Set on requests/responseson_http_request:  - actions:      - type: owasp-crs-requeston_http_response:  - actions:      - type: owasp-crs-response

CLI Flags

`url`

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

`traffic-policy-file`

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

`traffic-policy-url`

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

`pooling-enabled`

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

What else can I do with ngrok?

Use ngrok Kubernetes Operator: https://ngrok.com/docs/k8s/ (opens in a new tab)
Get started with Traffic Observability: https://ngrok.com/docs/obs/ (opens in a new tab)
Look into Identity and Access Management: https://ngrok.com/docs/iam/ (opens in a new tab)
Read ngrok's Security Best Practices: https://ngrok.com/docs/guides/security-dev-productivity/ (opens in a new tab)
Check out Gateway Examples Gallery: https://ngrok.com/docs/universal-gateway/examples/ (opens in a new tab)

Ending Notes

Get started with ngrok absolutely free of charge, sign up today!

The ultimate guide to ngrok: The ngrok cheat sheet

API service#

Web app#

SSH server#

Postgres server#

Any service or server on a different machine#

Restrict OAuth to specific emails#

Restrict OAuth to specific domains#

CLI Alternative#

Example Traffic Policy File#

Start Public Endpoint with forward-internal action#

Manage traffic in other ways#