The ngrok cheatsheet

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

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

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

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

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

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

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

1# Example: On localhost:30002ngrok http 3000

1# Example: On Port 222ngrok tcp 22

ngrok tcp 5432

ngrok http http://192.168.1.50:8080

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

nano policy.yaml

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

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

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

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

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

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

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

1# Create a private, internal agent endpoint only reachable via forward-internal2ngrok http 8080 --url https://api.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

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

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 }

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

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

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"

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

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"

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

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

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

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

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

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