Categories

Set up ngrok on Linux – Expose Your Localhost Online

Donate with

82uymVXLkvVbB4c4JpTd1tYm1yj1cKPKR2wqmw3XF8YXKTmY7JrTriP4pVwp2EJYBnCFdXhLq4zfFA6ic7VAWCFX5wfQbCC

Copy Monero Donation Address

Donate with

Donate BAT now

Verified BAT publisher

Installing ngrok on Linux — Expose your local server with a public URL

When developing integrations that require a publicly reachable callback or webhook endpoint (for example, working on the CleverReach API v3 where OAuth callbacks or live webhooks are needed), running everything locally can be inconvenient. This can be solved easily by using ngrok to expose a local development server and obtain a temporary or reserved public address. This article provides a clear, practical guide on how to install ngrok, authenticate it, open HTTP and TCP tunnels, inspect traffic, and use it for OAuth or webhook development.

Why ngrok?

• Creates a secure public URL that tunnels to your local port.
• Great for testing OAuth callbacks, webhooks, or sharing a running site with teammates.
• Includes an inspection UI so you can replay and debug requests.

Prerequisites

• A Linux machine (Debian/Ubuntu, Fedora, Arch, etc.)
• A local server running (for example on port 8080)
• An ngrok account (optional for free/basic; required for some features like reserved domains)

1. Install ngrok

There are multiple ways to install ngrok. Here are two reliable options:

Download binary and install globally

# Download (example for 64-bit Linux), unzip and move to /usr/local/bin wget https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip unzip ngrok-stable-linux-amd64.zip sudo mv ngrok /usr/local/bin/ sudo chmod +x /usr/local/bin/ngrok
Verify installation

ngrok version

Install via snap (if you prefer snaps)

sudo snap install ngrok # or for classic snap sudo snap install ngrok --classic 

Either method will give you the ngrok CLI. If you installed with the binary, you can place it in any folder in your $PATH (for example /usr/local/bin).

2. Authenticate ngrok (set your authtoken)

If you create an ngrok account, you get an authtoken in your dashboard. Setting the token links the CLI to your account and enables higher request limits and advanced features.

# Replace YOUR_AUTHTOKEN with the token from your ngrok dashboard ngrok authtoken YOUR_AUTHTOKEN 

This command saves your token in ~/.ngrok2/ngrok.yml. From then on you can create tunnels associated with your account.

3. Start an HTTP tunnel (expose a local web server)

If your app runs on http://localhost:8080, you can expose it with:

ngrok http 8080 

After starting, the terminal shows a forwarding address like https://abcd1234.ngrok.io. That is your public URL. Use that as the redirect URI for OAuth or as webhook callback URL in external services.

4. Forward other ports (TCP)

If you need to expose an SSH server, a database admin GUI, or any non-HTTP service, use a TCP tunnel. Note: TCP tunnels and reserved domains may require a paid plan depending on your ngrok account plan.

# Example: forward local SSH (port 22) to a public TCP endpoint ngrok tcp 22 

Terminal output will include an address like tcp://0.tcp.ngrok.io:12345. Connect to it with an SSH client that points to the given host and port.

5. Use the web inspection UI

ngrok runs an inspection and replay UI by default at http://127.0.0.1:4040. Open that in your browser to:

• See request/response details
• Replay requests (useful for webhook replay)
• View raw payloads and headers

6. Example: OAuth / Callback flow

Common scenario: an OAuth provider needs a redirect URI. Use the ngrok public URL as the redirect URI and map it to your local callback route.

# Suppose your app listens on /auth/callback on port 8080: # Public redirect URI example: https://abcd1234.ngrok.io/auth/callback 

Set that URL in the OAuth app configuration (on provider side). When the provider redirects, ngrok forwards the request to your local server and you can complete the OAuth flow locally.

7. Useful features and flags

• Region — Choose region (e.g., eu, us) to reduce latency:

  ngrok http --region=eu 8080

• Subdomain (paid) — Reserve a predictable subdomain (requires an authenticated account and plan):

  ngrok http -hostname=myapp.example.com 8080

• Basic auth — Protect your tunnel with username/password:

  ngrok http 8080 --auth="user:password"

• Config file — Define tunnels in ~/.ngrok2/ngrok.yml for reusable setups. Example snippet:

  authtoken: YOUR_AUTHTOKEN tunnels: web: proto: http addr: 8080 ssh: proto: tcp addr: 22 

8. Security considerations

• Do not expose sensitive admin panels or production databases to public URLs unless you add authentication and encryption.
• Use --auth or protect endpoints in your application when exposing them publicly.
• Terminate ngrok when not needed to avoid lingering public endpoints.

9. Debugging tips

• Open http://127.0.0.1:4040 to inspect requests and replay webhooks.
• If the OAuth provider rejects redirect URIs, confirm the exact URL (including trailing slash and protocol) and register it exactly as shown by ngrok.
• If you need a stable hostname, consider reserving a subdomain or using a paid plan.

10. Quick reference commands

# Start a basic HTTP tunnel to port 8080 ngrok http 8080
Start HTTP tunnel and choose region

ngrok http --region=eu 8080

Start a TCP tunnel (e.g., for SSH)

ngrok tcp 22

Set your authtoken (one time)

ngrok authtoken YOUR_AUTHTOKEN

Protect a tunnel with basic auth

ngrok http 8080 --auth="user:password"

Conclusion

ngrok offers a simple and efficient way to expose local development servers to the internet. It is especially useful for testing OAuth redirects, webhooks, and API integrations that require a live, publicly accessible URL. By creating secure tunnels, developers can simulate production environments directly from their local machines, inspect and replay traffic using the built-in web interface, and speed up the testing and debugging process — all without deploying to a remote server.