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

1# Install via Homebrew
2brew install ngrok
3
4# Add your authtoken
5ngrok config add-authtoken <token>
6
7# Start an endpoint
8ngrok http 80

Linux (opens in a new tab)

Bash

1# Install via Apt
2curl -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 ngrok
8# OR
9# Install via Snap
10snap install ngrok
11
12# Add your authtoken
13ngrok config add-authtoken <token>
14
15# Start an endpoint
16ngrok http 80

Windows (opens in a new tab)

Bash

1# Install via WinGet
2winget install ngrok -s msstore
3# OR
4# Install via Scoop
5scoop install ngrok
6
7# Add your authtoken
8ngrok config add-authtoken <token>
9
10# Start an endpoint
11ngrok http 80

Kubernetes (opens in a new tab)

Bash

1# Add ngrok Kubernetes Operator to Helm
2helm repo add ngrok https://charts.ngrok.com
3
4# Add ngrok API key and authtoken
5export NGROK_AUTHTOKEN=YOUR_NGROK_AUTHTOKEN
6export NGROK_API_KEY=YOUR_NGROK_API_KEY
7
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 (opens in a new tab)

Bash

1# Install via Docker
2docker pull ngrok/ngrok
3
4# Run ngrok via Docker
5docker run --net=host -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80

SDKs (opens in a new tab)

Bash

1# Node.js: https://ngrok.com/downloads/node-js
2npm install @ngrok/ngrok
3
4# Go: https://ngrok.com/downloads/go
5go get golang.ngrok.com/ngrok/v2
6
7# Python: https://ngrok.com/downloads/python
8python3 -m pip install ngrok
9
10# Rust: https://ngrok.com/downloads/rust
11# Install ngrok-rust package and the required dependencies
12cargo 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:8080
ngrok http 8080

Web app

Bash

# Example: On localhost:3000
ngrok http 3000

SSH server

Bash

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

1ngrok diagnose
2
3# To test IPv6 connectivity
4ngrok diagnose --ipv6 true
5
6# To test connectivity between the ngrok agent and all ngrok points of presence
7ngrok diagnose --region all
8
9# For a verbose report
10ngrok diagnose -w out.txt #OR
11ngrok 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

1# policy.yaml
2on_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 (opens in a new tab)

Bash

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

Restrict OAuth to specific emails

YAML

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

Restrict OAuth to specific domains

YAML

1# policy.yaml
2on_http_request:
3  - actions:
4      - type: oauth
5        config:
6          provider: google
7  - expressions:
8      - "!(actions.ngrok.oauth.identity.email.endsWith('@example.com'))"
9    actions:
10      - type: deny

Verify your webhooks (opens in a new tab)

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

YAML

1# policy.yaml
2on_http_request:
3  - actions:
4      - type: verify-webhook
5        config:
6          provider: slack
7          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

1# policy.yaml
2on_http_request:
3  - actions:
4      - type: verify-webhook
5        config:
6          provider: $PROVIDER # Example: GitHub
7          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-internal
ngrok http 8080 --binding=internal --url https://api.internal

Example Traffic Policy File

YAML

1# policy.yaml
2# Forward to an internal endpoint from a public endpoint
3on_http_request:
4  - actions:
5      - type: forward-internal
6        config:
7          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

1# policy.yaml
2# Route /api/* to api.internal, /app/* to app.internal
3on_http_request:
4  - expressions:
5      - "req.path.startsWith('/api/')"
6    actions:
7      - type: forward-internal
8        config:
9          url: https://api.internal
10  - expressions:
11      - "req.path.startsWith('/app/')"
12    actions:
13      - type: forward-internal
14        config:
15          url: https://app.internal

Route traffic by anything (opens in a new tab)

YAML

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

YAML

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

Add rate limiting (opens in a new tab)

YAML

1# policy.yaml
2# 10 requests per 60s window per client IP -> 429 on limit
3on_http_request:
4  - actions:
5      - type: rate-limit
6        config:
7          name: per-ip-60s
8          algorithm: sliding_window
9          capacity: 10
10          rate: "60s"
11          bucket_key:
12            - conn.client_ip

Block search and AI bots (opens in a new tab)

YAML

1# policy.yaml
2# Send a robots.txt denying crawlers
3on_http_request:
4  - expressions:
5      - "req.path == '/robots.txt'"
6    actions:
7      - type: custom-response
8        config:
9          status_code: 200
10          headers:
11            Content-Type: "text/plain"
12          body: |
13            User-agent: *
14            Disallow: /

YAML

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

YAML

1# policy.yaml
2# Also add X-Robots-Tag to all responses
3on_http_response:
4  - actions:
5      - type: add-headers
6        config:
7          headers:
8            X-Robots-Tag: "noindex, nofollow, noai, noimageai"

Add headers (opens in a new tab)

Via CLI

Bash

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

Via Traffic Policy

YAML

1# policy.yaml
2# Add headers on request/response
3on_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 (opens in a new tab)

Bash

1# Allow only 203.0.113.0/24; deny others
2ngrok http 8080 --cidr-allow 203.0.113.0/24
3
4# Or explicitly deny CIDRs
5ngrok http 8080 --cidr-deny 0.0.0.0/0

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

YAML

1# policy.yaml
2# Apply OWASP Core Rule Set on requests/responses
3on_http_request:
4  - actions:
5      - type: owasp-crs-request
6on_http_response:
7  - actions:
8      - type: owasp-crs-response

CLI Flags

`url`

Bash

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

`traffic-policy-file`

Bash

# 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`

Bash

# 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`

Bash

# 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 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#

Via CLI

Via Traffic Policy

CLI Flags#

url#

traffic-policy-file#

traffic-policy-url#

pooling-enabled#

What else can I do with ngrok?#

Ending Notes#

Related writing

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

CLI Flags

`url`

`traffic-policy-file`

`traffic-policy-url`

`pooling-enabled`

What else can I do with ngrok?

Ending Notes