What is ngrok and how to use it?

Leon Chase

19 Feb 2025 • 3 min read

What is ngrok?

ngrok is a tool that creates a secure tunnel from the public internet to your local machine. It allows you to expose a local server running on your machine (e.g., a web application or API) to the internet without needing to configure complex network settings like port forwarding or setting up a public IP address.

This is particularly useful for:

Testing Webhooks: If you're developing an application that needs to receive webhooks (e.g., from payment gateways, GitHub, or Slack), ngrok can expose your local server to the internet so external services can reach it.
Sharing Local Projects: You can share your local development environment with others (e.g., for collaboration or demos).
Accessing Local Services Remotely: Access your local services from anywhere in the world.
Developing APIs: Test and debug APIs by exposing them temporarily to external clients.

Key Features of ngrok

Secure Tunnels: ngrok creates HTTPS tunnels by default, ensuring secure communication.
Temporary URLs: Each ngrok session generates a unique URL (e.g., https://abcd1234.ngrok.io) that maps to your local server.
Custom Domains: Paid plans allow you to use custom domains for your tunnels.
Traffic Inspection: Inspect incoming HTTP requests, including headers, query parameters, and payloads.
Cross-Platform Support: Works on Windows, macOS, and Linux.

How to Use ngrok

Step 1: Install ngrok

Download ngrok:
- Go to the official website: https://ngrok.com.
- Download the version for your operating system.
Install ngrok:
- Extract the downloaded file and place the ngrok executable in a directory of your choice.
- Add the directory to your system's PATH for easy access.
Authenticate ngrok:
- Sign up for a free account at https://dashboard.ngrok.com/signup.
- After signing up, go to the Auth section of your dashboard to find your authtoken.
- Run the following command to authenticate ngrok:
```
ngrok config add-authtoken YOUR_AUTHTOKEN
```
  Replace YOUR_AUTHTOKEN with the token provided in your dashboard.

Step 2: Start a Local Server

Before using ngrok, ensure you have a local server running. For example:

A Flask app running on http://localhost:5000.
A Node.js app running on http://localhost:3000.

If you don’t have a server, you can create a simple one for testing:

Python Example:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    return "Hello, ngrok!"

if __name__ == '__main__':
    app.run(port=5000)

Run the server:

python app.py

Step 3: Expose Your Local Server

Once your local server is running, expose it to the internet using ngrok.

Run the following command:
```
ngrok http 5000
```
Replace 5000 with the port your local server is running on.

ngrok will generate a public URL (e.g., https://abcd1234.ngrok.io) that maps to your local server. You’ll see output like this:

Session Status                online
Account                       your-email@example.com
Version                       3.x.x
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://abcd1234.ngrok.io -> http://localhost:5000
Forwarding                    https://abcd1234.ngrok.io -> http://localhost:5000

Share the generated URL (https://abcd1234.ngrok.io) with others or use it to test webhooks.

Step 4: Inspect Traffic

ngrok provides a web interface for inspecting incoming traffic:

Open your browser and navigate to http://127.0.0.1:4040.
You’ll see a dashboard showing all HTTP requests made to your ngrok URL, including:
- Request headers and query parameters.
- Response status codes and payloads.
- Timing information.

This is helpful for debugging and monitoring your application.

Step 5: Advanced Usage

Here are some advanced features of ngrok:

Custom Subdomains (Paid Plans):
- Reserve a custom subdomain (e.g., https://myapp.ngrok.io) instead of a random one.
- Command:
```
ngrok http --subdomain=myapp 5000
```
TCP Tunnels:
- Expose non-HTTP services (e.g., SSH, databases) using TCP tunnels.
- Command:
```
ngrok tcp 22
```
Authentication:
- Protect your tunnel with basic authentication.
- Command:
```
ngrok http --auth="username:password" 5000
```
Configuration File:
- Create a configuration file (~/.ngrok2/ngrok.yml) to define default settings.
- Example:
```
authtoken: YOUR_AUTHTOKEN
tunnels:
  myapp:
    proto: http
    addr: 5000
```
Multiple Tunnels:
- Expose multiple services simultaneously by defining multiple tunnels in the configuration file.

Use Cases for ngrok

Webhook Testing:
- Many APIs (e.g., Stripe, GitHub, Slack) send webhooks to your server. Use ngrok to expose your local server for testing.
Remote Debugging:
- Debug applications running on your local machine by sharing them via ngrok.
Demo Applications:
- Share your local development environment with clients or team members for feedback.
Accessing Local Services:
- Access your local services (e.g., a media server or database admin panel) from anywhere.
IoT Development:
- Expose IoT devices or services running on your local network to the internet.

Limitations of the Free Plan

The free version of ngrok has some limitations:

Random subdomains for each session.
Limited to 40 connections per minute.
No custom domains or reserved subdomains.
Traffic logs are only available during the session.

For more advanced features, consider upgrading to a paid plan.

Conclusion

ngrok is a powerful and easy-to-use tool for exposing local servers to the internet. Whether you're testing webhooks, sharing projects, or debugging APIs, ngrok simplifies the process by creating secure tunnels with minimal setup. Its flexibility and ease of use make it an essential tool for developers working on web applications, APIs, or other networked services.

If you have specific questions about ngrok or need help with advanced configurations, feel free to ask!