Popular Searches

Debug Your Local Applications Over the Internet with Ngrok Tunnels

Illustration of Ngrok---a utility that assigns you a public URL and tunnels it to your localhost.

Ngrok is a utility that assigns you a public URL and tunnels it to your localhost. This allows anyone outside of your network to use the public URL to easily access your local development environment.

What Is Ngrok?

Say you’re developing a web app, and want to share it with your coworkers to have them test it out. Without ngrok, you could either upload it to a small server somewhere, which takes time and doesn’t copy over things like local databases, or portforward your router to point to your computer, which is clunky and doesn’t work everywhere.

Ngrok solves this by giving you a single URL that tunnels to your device. It acts like a VPN of sorts, and can tunnel past firewalls directly to your device. You can have multiple tunnels running simultaneously, and you can choose the ports and protocol for each one. For example, you could forward your web server running over HTTP on port 3000, and forward your database over a raw TCP connection over port 8080.

The ngrok client will automatically assign you a URL like yourapp.ngrok.io:1234. This is essentially an SSH tunnel, but the endpoint is managed for you by the ngrok service. Ngrok has paid plans, which allow you to run more tunnels with reserved URLs, but the free tier is good enough for most basic tunnelling and debugging.

Because the URLs are generated automatically on the free tier, ngrok isn’t suitable for running anything where uptime is a concern. But you shouldn’t be keeping a tunnel to your personal computer open all the time anyway, simply for security reasons. The same is true for port forwarding, but ngrok can be turned on and off, so it’s better in that regard.

Installing Ngrok

Install ngrok by going to ngrok's online dashboard and creating an account.

To get started, go to ngrok’s online dashboard and create an account. Once you’re authenticated, the setup is relatively simple; ngrok doesn’t need to be installed through a package manager, just download the binary for your system and unzip the file, either through your file explorer or with the unzip command.

From there, you’re good to start running ngrok, but you’ll probably want to move it out of your Downloads folder and into a place where you can access it from anywhere. On Linux and macOS, this place is stored in the PATH variable, which you can find by running:

echo $PATH

This usually includes /usr/local/bin/, so we can move ngrok there by running this command from the Downloads folder:

sudo mv ngrok /usr/local/bin/

Then, ngrok will work like a normal utility. On Windows, you’ll want to add a new folder to your system’s PATH.

Before running it though, you’ll need to authenticate it with your account. You can do this by copying the authtoken shown in step 3 of the dashboard, and pasting it in with the command:

ngrok authtoken xxxxxxxxxx

This connects your account and allows you to create tunnels.

How to Set Up Ngrok Tunnels

To create a tunnel, simply specify the local port to connect to and the protocol the tunnel will use. For example, to tunnel a local webserver, you’d run:

ngrok http 80

Which will open a GUI showing the current open connections and information about your session. The URL for the tunnel is shown under “Forwarding,” which you’ll want to copy.

A GUI showing current open connections and information about your session

You can also start multiple tunnels at once from a configuration file. This config file is located in your home directory, in ~/.ngrok2/ngrok.yml. By default, this file will be empty except for your authtoken. You can add tunnels manually:

  proto: http
  addr: 80
  proto: tcp
  addr: 9090

Which you can then start all at once using:

ngrok start --all

Or start manually by specifying the tunnel names. You can find all the tunnel properties along with more example config files in the ngrok docs.

You can also create ngrok tunnels programmatically with wrapper clients for your language. For example, using the Node wrapper, you could make your web server automatically forward itself with:

const url = await ngrok.connect({proto: 'http', addr: 80});

…which would store the forwarding URL in a variable for you to use.

Ngrok Inspector

Another feature that makes ngrok particularly useful for debugging web apps is the tunnel inspector. Whenever you start a tunnel, you’re also given a URL for a web interface, usually localhost:4040. If you open this up in your browser, you’ll see a list of all the requests going through the tunnel along with the content and response.

A list of all requests going through the tunnel along with content and response

It doesn’t beat an API development environment like Postman, but it’s still very useful for inspecting the traffic going between the client and server. It captures everything, including requests your application makes automatically.

There’s another tab here labeled “Status” that displays the health of your tunnel, including stats like connection duration and connections per second for each tunnel.

Anthony Heddings Anthony Heddings
Anthony Heddings is the resident cloud engineer for LifeSavvy Media, a technical writer, programmer, and an expert at Amazon's AWS platform. He's written hundreds of articles for How-To Geek and CloudSavvy IT that have been read millions of times. Read Full Bio »

The above article may contain affiliate links, which help support CloudSavvy IT.