The ultimate guide to ngrok: The ngrok cheat sheet

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

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# Add your authtoken
12ngrok config add-authtoken <token>
13# Start an endpoint
14ngrok http 80

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

1# Add ngrok Kubernetes Operator to Helm
2helm repo add ngrok https://charts.ngrok.com
3# Add ngrok API key and authtoken
4export NGROK_AUTHTOKEN=YOUR_NGROK_AUTHTOKEN
5export NGROK_API_KEY=YOUR_NGROK_API_KEY
6helm install ngrok-operator ngrok/ngrok-operator \
7  --namespace ngrok-operator \
8  --create-namespace \
9  --set credentials.apiKey=$NGROK_API_KEY \
10  --set credentials.authtoken=$NGROK_AUTHTOKEN

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

1# Node.js: https://ngrok.com/downloads/node-js
2npm install @ngrok/ngrok
3# Go: https://ngrok.com/downloads/go
4go get golang.ngrok.com/ngrok/v2
5# Python: https://ngrok.com/downloads/python
6python3 -m pip install ngrok
7# Rust: https://ngrok.com/downloads/rust
8# Install ngrok-rust package and the required dependencies
9cargo add ngrok -F axum && cargo add axum && cargo add tokio -F rt-multi-thread -F macros

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

1# Example: On localhost:3000
2ngrok http 3000

1# Example: On Port 22
2ngrok tcp 22

1ngrok tcp 5432

1ngrok http http://192.168.1.50:8080

1ngrok diagnose
2# To test IPv6 connectivity
3ngrok diagnose --ipv6 true
4# To test connectivity between the ngrok agent and all ngrok points of presence
5ngrok diagnose --region all
6# For a verbose report
7ngrok diagnose -w out.txt #OR
8ngrok diagnose --write-report out.txt

1nano policy.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

1ngrok http 8080 --traffic-policy-file=policy.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

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

1# policy.yaml
2on_http_request:
3  - actions:
4      - type: verify-webhook
5        config:
6          provider: slack
7          secret: $SLACK_TOKEN

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

1# policy.yaml
2on_http_request:
3  - actions:
4      - type: verify-webhook
5        config:
6          provider: $PROVIDER # Example: GitHub
7          secret: $PROVIDER_TOKEN

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

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

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

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

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 }

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

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

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: /

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

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"

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

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"

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

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

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

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

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

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