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
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:
This usually includes /usr/local/bin/, so we can move ngrok there by running this command from the Downloads folder:
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:
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:
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.
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:
Which you can then start all at once using:
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:
…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.
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.
