The ngrok Cheat Sheet

May 12, 2022

min read

The biggest challenge of ngrok isn’t getting started. In fact, that’s the easiest part. You can start as simply as

ngrok http 80

and you have your local server online in one line. Quick, simple, and to the point.

Instead, the biggest challenge is two fold: knowing what you can do and then knowing how to do it. Towards that goal, our documentation walks you through every option, configuration, and setting you can use but even that can be daunting.

As of today, we’ve launched the ngrok Cheat Sheet in both pdf and png form.

The ngrok Cheat Sheet walks you through each of the core concepts starting from the basics. Print it and hang it on your wall or download it and keep it on hand.

Installation

1. Download ngrok

Windows:

choco install ngrok

Mac:

brew install ngrok/ngrok/ngrok

Linux:

snap install ngrok

Or via another package manager: https://ngrok.com/ngrok.com/download‍

2. Sign up and get an authtoken

3. Add the authtoken to the ngrok agent

ngrok config add-authtoken

Expose different types of servers

Web server (port 8080):

ngrok http 8080

File or folder:

ngrok http "file:///C:\temp"

SSH server (port 22):

ngrok tcp 22

Postgres server (port 5432):

ngrok tcp 5432

RDP server (port 3389):

ngrok tcp 3389

Server in a diff machine:

ngrok http 10.0.0.2:8080

Add Social Login

Facebook:‍

ngrok http 8080 \
    --oauth=facebook

Google for specific email domains:‍

ngrok http 8080 \
    --oauth=google \
    --oauth-allow-domain=example.com

Github with consent for repository management:

ngrok http 8080 \
    --oauth=github \
    --oauth-scope=repo

For more providers, visit our doc

Add webhook verification

Slack:

ngrok http 8080 \
    --verify-webhook=slack \
    --verify-webhook-secret=secret-token

Shopify:

ngrok http 8080 \
    --verify-webhook=shopify \
    --verify-webhook-secret=secret-token

Stripe:

ngrok http 8080 \
    --verify-webhook=stripe \
    --verify-webhook-secret=secret-token

Twilio:

ngrok http 8080 \
    --verify-webhook=twilio \
    --verify-webhook-secret=secret-token

Github:

ngrok http 8080 \
    --verify-webhook=github \
    --verify-webhook-secret=secret-token

Intercom:

ngrok http 8080 \
    --verify-webhook=intercom \
    --verify-webhook-secret=secret-token

Sendgrid:

ngrok http 8080 \
    --verify-webhook=sendgrid \
    --verify-webhook-secret=secret-token

‍For more providers, visit our doc

Other cool features

Allow access only to your IP:

ngrok http 8080 \
    --cidr-allow $(curl http://ifconfig.me/ip)/32

‍Deny access to any IPv6 requesters:‍

ngrok http 8080 \
    --cidr-deny ::/0

Add Circuit breaking (reject requests when 5XX responses exceed a 15% ratio):‍

ngrok http 8080 \
    --circuit-breaker 0.15

Add HTTP compression (gzip compress http responses):‍

ngrok http 8080 \
    --compression

Add requester's country to request header:‍

ngrok http 8080 \
    --request-header-add "country: \${.ngrok.geo.country_code}"

Add requester's geo latitude to request header::‍

ngrok http 8080 \
    --response-header-add "geo-lat: \${.ngrok.geo.latitude}"

Add security header to HTTP response::

ngrok http 8080 \
    --response-header-add "content-security-policy: self;"

‍For more providers, check our modules and http headers

Or mix and match like a mad scientist

HTTP access with Facebook Login, compression, and circuit-breaker at 50%:

ngrok http 8080 \
    --oauth=facebook \
    --compression \
    --circuit-breaker 0.5

‍SSH access restricted to your IP:‍

ngrok tcp 22 \
    --cidr-allow $(curl http://ifconfig.me/ip)/32

Access to a file only for your best friend with Google Social Auth:

ngrok http "file:///C:\super-important\file.pdf" \
    --oauth=google \
    --oauth-allow-email=mybff@gmail.com

What's next?

In addition to development, you can use ngrok to:

Enable remote access without VPNs
Access and managing remote software agents and IoT devices
Enable access to web applications in production

‍

Share this post

Keith Casey

Keith Casey serves on the Product/GTM Team at ngrok helping teams launch their systems faster and easier than ever before. Previously, he served on the Product Team at Okta working on Identity and Authentication APIs, as an early Developer Evangelist at Twilio, and worked to answer the Ultimate Geek Question at the Library of Congress. His underlying goal is to get good technology into the hands of good people to do great things. In his spare time, he writes at CaseySoftware.com and lives in the woods. He is also a co-author of A Practical Approach to API Design.

← back to index