Ngrok Tutorial: Complete Guide from Beginner to Advanced — Installation, Configuration, Tunnels, Security & Port Forwarding

ngrok is one of the easiest tools for exposing a local application or development server to the internet through a secure public endpoint. Developers, cybersecurity students, penetration testers, API developers, and security researchers commonly use ngrok to test webhooks, share localhost applications, demonstrate projects, and access development services remotely.

In this complete ngrok tutorial, you will learn everything from ngrok installation and basic configuration to advanced tunnels, custom configuration, authentication, traffic policies, multiple tunnels, HTTPS, TCP forwarding, security controls, and troubleshooting.

Ethical-use note: Only expose applications and systems that you own or have explicit permission to test. Never use a public tunnel to expose sensitive services, credentials, private databases, or unauthorized systems.

What Is ngrok?

ngrok is a tunneling platform that creates a public endpoint and forwards incoming traffic to an application running on your local machine.

For example, suppose your website is running locally:

http://localhost:3000

Normally, only your computer can access it.

With ngrok, you can create a public endpoint that forwards requests to your local application:

Internet
    ↓
https://your-ngrok-endpoint.ngrok.app
    ↓
ngrok tunnel
    ↓
localhost:3000
    ↓
Your application

This is especially useful when you need to:

• Share a localhost website
• Test webhooks
• Test APIs
• Demonstrate a development project
• Test mobile applications against a local API
• Share a development environment temporarily
• Test authentication flows
• Receive callbacks from external services
• Experiment with HTTPS locally

Why Use ngrok?

There are several situations where ngrok can save a lot of time.

1. Share localhost

Instead of deploying a development application to a server, you can temporarily expose your local application through an ngrok endpoint.

2. Test webhooks

Services such as GitHub, payment platforms, SaaS applications, and other APIs may need a publicly reachable webhook URL.

ngrok can forward those requests to your local development server.

3. Test HTTPS

Your local application may be running on HTTP while your external integration requires HTTPS.

ngrok can provide a public HTTPS endpoint for development and testing.

4. API development

You can expose a local API and test it from another device or external application.

5. Cybersecurity labs

ngrok can be useful in authorized security labs for testing how applications behave when exposed through a public endpoint.

How Does ngrok Work?

The basic architecture looks like this:

Internet
                    │
                    ▼
          Public ngrok Endpoint
                    │
                    ▼
              ngrok Tunnel
                    │
                    ▼
             Local Machine
                    │
                    ▼
             localhost:3000
                    │
                    ▼
             Your Web App

Your local service does not necessarily need to be directly exposed through your router.

The ngrok agent establishes the connection and forwards traffic between the public endpoint and your local service.

Prerequisites

Before installing ngrok, make sure you have:

• A working Linux system
• Internet connectivity
• A local application or service
• A ngrok account
• Terminal access

For this tutorial, examples will use Kali Linux, but the concepts also apply to other Linux distributions.

How to Install ngrok on Kali Linux

The recommended installation method is through the official ngrok APT repository.

Step 1: Add the ngrok repository

Run:

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null

Then add the repository:

echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list

Update the package index:

sudo apt update

Install ngrok:

sudo apt install ngrok

The official ngrok Linux installation documentation currently provides this APT-based installation flow.

Verify the ngrok Installation

After installation, check the version:

ngrok version

You can also check the available commands:

ngrok help

If the installation was successful, ngrok should display its version and command information.

Step 2: Create an ngrok Account

You need an ngrok account to authenticate the agent.

After signing in to your ngrok account, obtain your authentication token from the ngrok dashboard.

Do not publish your authentication token in:

• GitHub repositories
• Blog posts
• Screenshots
• YouTube videos
• Public configuration files
• Chat messages

Treat the token like a credential.

Step 3: Configure Your ngrok Authtoken

Run:

ngrok config add-authtoken "<YOUR_AUTHTOKEN>"

Example:

ngrok config add-authtoken "YOUR_TOKEN_HERE"

The official ngrok documentation uses ngrok config add-authtoken for agent authentication.

After configuration, verify your configuration:

ngrok config check

The config check command can also show the location of the ngrok configuration file.

Where Is the ngrok Configuration File?

On Linux, the default configuration file is:

~/.config/ngrok/ngrok.yml

You can check its location with:

ngrok config check

ngrok’s current agent documentation lists ~/.config/ngrok/ngrok.yml as the default Linux configuration path.

Your First ngrok Tunnel

Now let’s expose a local application.

Suppose your application is running on:

localhost:3000

Run:

ngrok http 3000

ngrok will establish a public endpoint and forward incoming HTTP/HTTPS traffic to port 3000.

The official documentation uses the same pattern:

ngrok http 80

where the port should be replaced with the port used by your application.

Example: Expose a Python HTTP Server

If you want to quickly test ngrok without installing a web framework, create a test directory:

mkdir ngrok-test
cd ngrok-test

Create a simple file:

echo "Hello from localhost" > index.html

Start Python’s HTTP server:

python3 -m http.server 8000

Your local server is now available at:

http://127.0.0.1:8000

Open another terminal and run:

ngrok http 8000

ngrok will provide a public endpoint that forwards traffic to your local server.

Understanding Port Forwarding with ngrok

A common question is:

Does ngrok forward my router port?

Not in the traditional sense.

ngrok creates a tunnel between the public ngrok infrastructure and the local ngrok agent.

For example:

Public Internet
      │
      ▼
https://example.ngrok.app
      │
      ▼
ngrok infrastructure
      │
      ▼
ngrok agent
      │
      ▼
127.0.0.1:8000

This makes ngrok convenient for development environments where configuring router port forwarding would otherwise be unnecessary.

Expose Different Local Ports

The basic syntax is:

ngrok http PORT

Examples:

ngrok http 3000

ngrok http 5000

ngrok http 8000

ngrok http 8080

For a local development server running on port 5173:

ngrok http 5173

Always replace the port with the port where your application is actually listening.

How to Find Which Port Your Application Uses

On Linux, you can inspect listening services using:

sudo ss -tulpn

You can also search for a specific port:

sudo ss -tulpn | grep 8000

For example, if your application is listening on port 3000, you can expose it with:

ngrok http 3000

HTTP vs HTTPS with ngrok

When you run:

ngrok http 3000

ngrok provides a public endpoint that can be accessed using HTTPS.

This is extremely useful for development because many modern services require HTTPS for callbacks, authentication, or webhook testing.

However, remember:

HTTPS between the visitor and the public endpoint does not automatically make an insecure application secure.

Your application still needs proper:

• Authentication
• Authorization
• Input validation
• Session security
• API security
• Secret management

Running ngrok with a Local Hostname

Sometimes your application is configured for a specific hostname rather than localhost.

You can specify the host using:

ngrok http http://127.0.0.1:3000

Or:

ngrok http http://localhost:3000

This can be useful when troubleshooting applications that behave differently depending on the upstream address.

Using the ngrok Configuration File

For simple testing, this is enough:

ngrok http 3000

But if you regularly use ngrok, a configuration file becomes much more useful.

The ngrok agent supports a YAML configuration file for running multiple endpoints and configuring advanced settings.

First check the configuration location:

ngrok config check

Then edit the configuration file:

nano ~/.config/ngrok/ngrok.yml

Example ngrok Configuration

A basic configuration can define named endpoints.

For example:

version: "3"

agent:
  authtoken: YOUR_AUTHTOKEN

endpoints:
  - name: web
    upstream:
      url: 3000

  - name: api
    upstream:
      url: 5000

Configuration syntax can change between ngrok agent versions, so always validate your configuration against the current ngrok documentation before deploying a production setup.

Why Named Endpoints Are Useful

Instead of remembering:

ngrok http 3000

you can organize multiple services using meaningful names.

For example:

web
api
dashboard
testing

This becomes particularly useful when working with multiple local applications.

Running Multiple ngrok Tunnels

Suppose you have:

Frontend → localhost:3000
API      → localhost:5000
Admin    → localhost:8080

You may want to expose multiple services.

Instead of manually starting each tunnel, define your endpoints in your configuration and start the required endpoints.

This is one of the main advantages of using an agent configuration file: ngrok supports configuration for multiple endpoints and configuration merging.

Configuration File Validation

Whenever you modify your configuration, run:

ngrok config check

This is a simple but important troubleshooting step.

If ngrok reports a configuration error, fix the YAML syntax before starting your endpoint.

Common YAML problems include:

• Incorrect indentation
• Missing colon
• Incorrect nesting
• Invalid field names
• Incorrect quotation marks

ngrok for Localhost Development

One of the most popular use cases is sharing a local development server.

For example:

React/Vite
localhost:5173

Run:

ngrok http 5173

For a Node.js application:

localhost:3000

Run:

ngrok http 3000

For a Flask application:

localhost:5000

Run:

ngrok http 5000

For Django:

localhost:8000

Run:

ngrok http 8000

ngrok for Webhook Testing

Webhooks are one of the best use cases for ngrok.

Imagine your local application has:

POST /webhook

and is running on:

localhost:3000

Start:

ngrok http 3000

You can then configure your external service to send webhook requests to your public ngrok endpoint.

The request flow becomes:

External Service
       │
       ▼
Public ngrok URL
       │
       ▼
ngrok Tunnel
       │
       ▼
localhost:3000
       │
       ▼
/webhook

This allows you to develop and debug webhook integrations without deploying your application first.

Testing APIs Through ngrok

Suppose your API is running locally:

localhost:5000

Start:

ngrok http 5000

You can then test API endpoints through the public URL.

For example:

curl https://YOUR-NGROK-DOMAIN/api/users

The request is forwarded to your local API.

Important Security Warning for APIs

Do not expose an API simply because you can.

Before making a local API publicly accessible, verify:

• Authentication is enabled
• Authorization is correct
• Debug mode is disabled
• Sensitive endpoints are protected
• Database credentials are not exposed
• API keys are not hardcoded
• Rate limiting is considered
• Logs do not contain secrets

A public tunnel turns a local development service into something reachable from the internet.

Securing an ngrok Endpoint

One of the most important advanced topics is access control.

ngrok’s Traffic Policy system can be used for authentication, rate limiting, request filtering, URL rewriting, IP restrictions, and other traffic controls.

Available authentication approaches include:

• Basic Authentication
• OAuth
• OpenID Connect
• JWT validation
• IP restrictions
• Mutual TLS

Protect an Endpoint with Basic Authentication

Basic authentication is useful for quick demos and internal development tools.

A Traffic Policy can require a username and password before requests reach your application.

Example:

on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - username: demo
              password: CHANGE_THIS_PASSWORD

ngrok’s current Basic Auth action supports username/password credentials and returns 401 Unauthorized when authentication fails.

Security recommendation

Never use simple passwords such as:

password123
admin
12345678

Use a strong password and avoid putting real production credentials directly into publicly shared configuration files.

Protect ngrok with OAuth

For a more user-friendly authentication experience, OAuth can be used.

For example, ngrok supports managed OAuth providers including:

• Google
• GitHub
• GitLab
• LinkedIn
• Microsoft
• Twitch

A basic Traffic Policy can look like:

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google

Then start the endpoint with the policy:

ngrok http 3000 --traffic-policy-file oauth.yml

The user will be redirected to the authentication provider before reaching the application.

Restrict Access to Specific Users

Authentication alone may not always be enough.

You may want only selected users to access your development application.

For example, after OAuth authentication, a policy can check the authenticated user’s email address.

Conceptually:

Visitor
   ↓
OAuth Login
   ↓
Identity verified
   ↓
Email allowed?
   ├── YES → Application
   └── NO  → Deny

This is useful when sharing a private development application with a small team.

ngrok’s documentation provides examples for restricting access based on authenticated email addresses and domains.

Restrict Access by IP Address

Another security option is IP-based access control.

Traffic Policy supports allow and deny lists for source IP addresses.

Conceptual example:

on_http_request:
  - actions:
      - type: restrict-ips
        config:
          enforce: true
          allow:
            - 203.0.113.10/32

This can be useful when a service should only be reachable from trusted networks.

Rate Limiting with ngrok

Public endpoints can receive unexpected traffic.

Rate limiting can help control how many requests an endpoint accepts within a given period.

For example:

Client
  ↓
ngrok
  ↓
Rate Limit
  ↓
Application

Traffic Policy supports rate-limit actions and can use different rules for authenticated and unauthenticated traffic.

This is particularly useful when testing APIs or sharing development services.

Traffic Policy: The Advanced ngrok Layer

Traffic Policy is one of the most powerful advanced features in ngrok.

Instead of simply forwarding traffic, you can apply rules before the request reaches your application.

Traffic Policy can be used to:

• Authenticate users
• Restrict IP addresses
• Rate-limit requests
• Rewrite URLs
• Modify headers
• Block unwanted traffic
• Validate requests
• Route traffic
• Apply security controls

The general structure is:

Incoming Request
       ↓
Traffic Policy
       ↓
Authentication
       ↓
IP Filtering
       ↓
Rate Limiting
       ↓
Routing / Transformation
       ↓
Local Application

Example Traffic Policy File

Create:

nano policy.yml

Example:

on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - username: demo
              password: CHANGE_THIS_PASSWORD

Then start your application:

ngrok http 3000 --traffic-policy-file policy.yml

This adds an authentication layer before traffic is forwarded to your application.

Combining Authentication and IP Restrictions

For more advanced environments, you can combine multiple controls.

For example:

Internet
   ↓
ngrok Endpoint
   ↓
IP Restriction
   ↓
OAuth
   ↓
Rate Limit
   ↓
Local Application

This provides multiple layers of protection.

The exact policy should depend on the application and threat model rather than blindly copying a configuration from a tutorial.

TCP Tunnels

ngrok is not limited to HTTP applications.

For services that require TCP connectivity, ngrok can provide TCP endpoints depending on your account and plan capabilities.

A typical command is:

ngrok tcp PORT

For example:

ngrok tcp 22

Important security warning

Do not expose SSH or another sensitive administrative service publicly unless you understand exactly what you are doing and have strong authentication and access controls in place.

For learning, use a deliberately isolated lab environment.

ngrok and SSH

A common educational example is exposing SSH through a TCP tunnel.

However, public SSH exposure can create significant security risk.

If you are testing SSH in an authorized lab:

• Use key-based authentication
• Disable password authentication where appropriate
• Use a non-privileged account
• Keep the system patched
• Restrict access
• Monitor logs
• Never expose production credentials

For most beginners, HTTP tunneling is a much safer way to learn ngrok.

ngrok for Local Cybersecurity Labs

ngrok can be useful in cybersecurity education when used in a controlled environment.

Examples include:

• Testing webhook security
• Testing authentication flows
• Studying HTTP request behavior
• Testing API security
• Demonstrating secure tunnels
• Testing application access controls
• Building authorized CTF/lab infrastructure

Always make sure the system and application belong to you or that you have explicit authorization.

ngrok vs Traditional Router Port Forwarding

Traditional port forwarding typically looks like:

Internet
   ↓
Public IP
   ↓
Router
   ↓
Port Forwarding Rule
   ↓
Local Machine
   ↓
Application

With ngrok:

Internet
   ↓
ngrok Endpoint
   ↓
ngrok Tunnel
   ↓
Local Agent
   ↓
Application

Traditional port forwarding

Advantages:

• Direct network control
• Useful for permanent infrastructure
• Full control over router configuration

Disadvantages:

• Router configuration required
• Firewall configuration required
• Public IP considerations
• More network administration

ngrok

Advantages:

• Fast setup
• Excellent for development
• HTTPS endpoint
• Easy webhook testing
• No need to manually configure router port forwarding for the basic tunnel workflow

Disadvantages:

• Depends on the ngrok service
• Account/plan capabilities can affect available features
• Publicly exposed applications still need security controls

Common ngrok Commands Cheat Sheet

Check version

ngrok version

Show help

ngrok help

Check configuration

ngrok config check

Add authentication token

ngrok config add-authtoken "<YOUR_AUTHTOKEN>"

Start HTTP tunnel

ngrok http 3000

Start HTTPS-accessible endpoint for local HTTP service

ngrok http 3000

Start TCP tunnel

ngrok tcp 8080

Start with Traffic Policy

ngrok http 3000 --traffic-policy-file policy.yml

Troubleshooting ngrok

Problem 1: ngrok: command not found

Check whether ngrok is installed:

which ngrok

If nothing is returned, install ngrok or verify that its installation directory is in your PATH.

Problem 2: Authentication Error

If ngrok reports an authentication problem:

ngrok config check

Then configure your token again:

ngrok config add-authtoken "<YOUR_AUTHTOKEN>"

Never paste your real token into public posts or screenshots.

Problem 3: Local Application Is Not Working

First test your application directly:

curl http://127.0.0.1:3000

If the local request fails, ngrok cannot fix the application itself.

The correct troubleshooting order is:

Local Application
       ↓
Local Port
       ↓
ngrok Agent
       ↓
Public Endpoint

Always verify the local service first.

Problem 4: Wrong Port

Check listening ports:

sudo ss -tulpn

Then expose the correct port.

For example:

ngrok http 8000

Problem 5: Configuration Error

Run:

ngrok config check

Then inspect:

nano ~/.config/ngrok/ngrok.yml

Check YAML indentation and field names.

Best Practices for Using ngrok

If you regularly use ngrok, follow these practices.

1. Never expose secrets

Do not expose:

.env files
database credentials
API keys
private admin panels
SSH credentials
cloud credentials

2. Use authentication

If your application is not meant for everyone, add authentication.

3. Keep development services isolated

Do not expose production systems simply for testing.

4. Use HTTPS

Prefer HTTPS endpoints when transmitting sensitive development data.

5. Monitor traffic

Watch application and ngrok logs during testing.

6. Stop tunnels when finished

A temporary development endpoint does not need to remain online indefinitely.

7. Rotate compromised tokens

If your ngrok authentication token is accidentally published, treat it as compromised and replace it.

ngrok Security Checklist

Before exposing a local application, ask:

[ ] Do I own this application?
[ ] Do I have authorization to expose it?
[ ] Is authentication enabled?
[ ] Is debug mode disabled?
[ ] Are secrets protected?
[ ] Are API keys hidden?
[ ] Is the database protected?
[ ] Are unnecessary endpoints disabled?
[ ] Is rate limiting required?
[ ] Should IP restrictions be enabled?
[ ] Do I need OAuth?
[ ] Will I stop the tunnel after testing?

If you cannot answer these questions confidently, do not expose the service publicly.

Beginner to Advanced ngrok Learning Path

If you are completely new to ngrok, learn it in this order.

Level 1 — Beginner

Learn:

What is ngrok?
↓
Install ngrok
↓
Authenticate
↓
Run ngrok http
↓
Expose localhost

Start with:

ngrok http 3000

Level 2 — Intermediate

Learn:

Configuration files
↓
Multiple endpoints
↓
Webhook testing
↓
API testing
↓
HTTPS
↓
Request inspection

Level 3 — Advanced

Learn:

Traffic Policy
↓
OAuth
↓
Basic Auth
↓
IP restrictions
↓
Rate limiting
↓
Request filtering
↓
URL rewriting

Level 4 — Security & Production

Learn:

Authentication
↓
Authorization
↓
Network restrictions
↓
Traffic policies
↓
Monitoring
↓
Secret management
↓
Zero-trust architecture

Frequently Asked Questions About ngrok

Is ngrok free?

ngrok offers account-based access with different capabilities depending on the current product and plan. Always check the current ngrok pricing and feature documentation before designing a production workflow.

Is ngrok safe?

ngrok is a legitimate tunneling platform, but exposing an application to the internet creates security considerations. The safety of your setup depends heavily on what you expose and how you protect it.

Can I use ngrok on Kali Linux?

Yes. The official Linux installation flow can be used on supported Linux environments, including Kali Linux setups where the package requirements are compatible.

Can ngrok expose localhost?

Yes. This is one of its most common development use cases.

For example:

ngrok http 3000

can expose a local HTTP service running on port 3000.

Can I use ngrok for webhooks?

Yes. ngrok is commonly used to provide publicly reachable endpoints for webhook development and testing.

Can ngrok provide HTTPS?

Yes. The standard HTTP tunnel workflow provides a public HTTPS endpoint for your local HTTP application.

Can ngrok expose TCP services?

Yes, ngrok supports TCP endpoints, subject to the current account and product capabilities.

Can I run multiple ngrok tunnels?

Yes. The agent configuration system supports configuring multiple endpoints.

How do I secure an ngrok tunnel?

You can use controls such as:

• Basic Auth
• OAuth
• OIDC
• IP restrictions
• Rate limiting
• Traffic Policy
• mTLS where appropriate

Is ngrok a VPN?

No.

ngrok is primarily a tunneling and application delivery platform. It should not be treated as a general-purpose replacement for a VPN.

Conclusion

ngrok makes it extremely easy to connect a local application with the public internet without manually configuring traditional router port forwarding.

For beginners, the most important command is:

ngrok http 3000

But ngrok becomes much more powerful when you move beyond basic tunnels and start using:

Configuration Files
        ↓
Multiple Endpoints
        ↓
HTTPS
        ↓
Webhook Testing
        ↓
Authentication
        ↓
OAuth
        ↓
IP Restrictions
        ↓
Rate Limiting
        ↓
Traffic Policy

The most important lesson is that making localhost public is easy; making a public application secure is the real challenge.

Use ngrok for legitimate development, testing, education, and authorized security research — and always protect publicly reachable services with appropriate authentication and access controls.

Quick ngrok Command Reference

# Check version
ngrok version

# Check configuration
ngrok config check

# Add authentication token
ngrok config add-authtoken "<YOUR_AUTHTOKEN>"

# Expose localhost:3000
ngrok http 3000

# Expose localhost:5000
ngrok http 5000

# Expose localhost:8000
ngrok http 8000

# TCP tunnel
ngrok tcp 8080

# Start HTTP endpoint with Traffic Policy
ngrok http 3000 --traffic-policy-file policy.yml

Official ngrok Documentation

For the latest commands, supported configuration fields, account limitations, and advanced features, always verify against the official ngrok documentation because the agent and platform capabilities can evolve over time.