What is ngrok and what is it used for?
Ngrok is an internet application, which enables one to securely
expose their local computer (local development server) to the internet using a
public url. In other words, you can make your local computer an internet server without having a dedicated IP address. All you need to do is install ngrok and have your computer connected to the internet.
By exposing your computer, we mean exposing the applications running in your computer, including databases, so that they are accessed from anywhere.
Your machine will be accessed using a subdomain on ngrok.com domain. For instance, once you start ngrok service in a given computer, it will generate a URL like
de345.ngrok.com, which you use to access the computer where ngrok is running in.
Ngrok is free for basic features with usage limitation. You can use the paid version to unlock more features such as custom subdomains and more.
The beauty is that you can instruct ngrok to expose your machine using any port e.g. if you have an app or service running on port
8000, ngrok can be instructed to run to expose that port.
You can start ngrok on any port in your computer
The following diagram can enable you to understand better.
The relative position of all entities taking part in the use of ngrok application
Objectives of this walk-through
- To identify use cases of ngrok usage.
- To provide a procedure of setting up and using ngrok in a windows computer to access both web and database applications.
- To identify the reasons why ngrok may not be working in your machine.
Ngrok usage use cases
There are many reasons why you may want to access your local computer over the internet. The following are examples of cases of ngrok usage.
1. Web application demo to the end-users/clients
Suppose you are building a web application and you have to demo it to your end-users (test users) or your clients. Instead of deploying to a live server, you can let ngrok generate a URL pointing to your computer and share it with your users.
However, note that the number of users who can access your local machine will depend on the processing power and memory of your computer as well as the ngrok plan you are using.
2. Testing a web application from different clients
If you are developing an application and you want to test it from a variety of clients, ngrok will generate a URL, which you can distribute to the target clients. In this same idea, if you are building an app, which has a mobile client (e.g. an android client), the ngrok generated URLs can simulate public URLs.
3. Testing Webhooks
A webhook or generally referred to as a callback URL, a methodology used in API integration i.e where 2 applications exchange information, and more specifically, application
A must notify application
B when some event occurs.
Suppose you are building an e-commerce system and you use an external payment system to accept payments. What happens is that you must put a URL in the payment system so that the payment system can use it to notify your e-commerce website when a user has made a payment. The ngrok generated URL can be used for this purpose to test the behaviour of the system before deployment.
3. Letting another application access a database application on your local computer.
If you have an external application, which needs to access a database running on your local computer, it is possible with ngrok. We know Database Management Systems (DBMS) are
TCP applications. The good news is, ngrok supports this protocol as we will discover in the next section.
Installing and using ngrok
1. Visit this link (ngrok website) and click on “Download for windows”. You will get a zip file downloaded.
2. Move the downloaded zip to a favourite location and extract it. Inside the folder from the extraction, you will see a small executable file,
3. Double-click on the ngrok file. It will open a
cmd with the extracted folder as the present working directory,
pwd. See below.
It can be observed that
ngrok gives examples of usage of its commands. Our objective is to expose a local computer to the internet.
Additionally, you can observe that ngrok supports both
4. To expose a web application running in your computer on port
80, you can run this command on the terminal.
ngrok http 80
Below, you will see that ngrok will create a URL of the form
http(s)://<random_text>.ngrok.com, which is mapped to port
80 on your computer.
From the screenshot, there are at least
5 data points of interest;
i) You can stop the ngrok service by pressing
ctrl + C.This command will kill ngrok service.
ii) Ngrok provides a web interface used to inspect its usage. The web interface is accessed using
http://localhost:4040. If you are not sure if ngrok is running, you can use this URL to test if its web interface is accessible.
iii) The public URLs provided are both HTTP and HTTPS. Some applications, especially when testing webhooks (see use case 3 above), may require that you use HTTPS.
iv) Ngrok shows you the account details including the pricing plan that you are on.
v) Ngrok shows you the region where the server you are interacting with is located. In the example above, the region is the United States (US).
Exposing database application
DBMS such as
tcp applications. Ngrok allows you to expose database applications on TCP protocol the same way we did with HTTP applications, using the port number on which they are running.
Exposing MySQL database on default port i.e. port 3306
You will need to run the following command:
ngrok tcp 3306
The output of the above command is shown below.
If you are connecting to the database use
0.tcp.ngrok.io:13003 as your hostname. Notice that we have not included
tcp:// in the hostname.
To expose the Postgres database on the default port, then you will run the following command:
ngrok tcp 5432
Protecting your ngrok URLs using passwords
When you expose your computer to a public URL, it means that any person having access to the URL can access your computer even though that was not the intention. The URL may even be guessed.
If you had a select group, you would create a URL, which requires that users provide a username and password for them to access the service.
This can be achieved by running the ngrok command as follows:
ngrok http -auth="username here:password here" 80
When you share the public URL, users will be asked to enter a username and password as shown below
Modifying/re-writing request headers
You will realize that ngrok forwards any HTTP headers as they come without changing anything. However, sometimes you may want to modify the headers.
The following examples explain why you may need to carry out the modification:
i) Modification – Rewriting the host header to something else. For instance, your local server is configured with virtual machines (VM) and you want to use a specific VM as your host.
In this case, you can have something like this:
ngrok http -host-header=decode.local.vh 80
decode.local.vh is the name of the VM with a service running on port
ii) Configure ngrok’s CORS headers
In cases where the hostname is different from that of forwarding host address, you can rewrite the hostname to match that of the forwarding address. For example, same address but different ports – if the forwarding address’ port number is
8080, then you can do it this way;-
ngrok http -host-header=rewrite 8080 //We have made the host port number to be similar to forwading address port number.
iii) Ngrok allows you to modify request headers via,
replaying which is possible by using the web interface. You will need to select a request from the web interface, then click on ‘Replay with modification’. You will see the interface below
Click on ‘Replay’ to resend the request. We have now re-sent the request with a new header,
Why Ngrok is not working on my computer?
Our earlier discussion showed that the main function of ngrok is to expose your local computer using a URL. But sometimes, it may not be working, and it may be because of any of the following reasons. Note that this list is not exhaustive.
- You are using a free ngrok plan with certain limitations. For instance, the free ngrok plan allows only 1 ngrok process, 4 tunnels (4 URLs) per ngrok process and 40 connections per minute.
- ngrok service may have stopped. We earlier noticed that you can use
http://localhost:4040/to check if ngrok web interface is reachable. If it is not reachable, then ngrok service is not running.
- A problem with ngrok’s CORS headers. For instance, if the host address is different from a forwarding address, there will be an error. Fortunately, ngrok allows you to re-write request headers as seen earlier.
- If you are accessing some service running on your local computer, then you may have forgotten to start such a service. When accessing your machine using ngrok’s generated public URL, you are likely to see, Failed to complete tunnel connection, if the service you want to access was not started in the local machine.
- When testing a webhook, the API you are testing requires a URL pointing to the application being tested. If you use HTTPS, it may not work with the self-signed certificate on your local computer. In this case, you may only use HTTP. See an example here from Twilio.
The discussion we have had here focused on the most common use cases of ngrok. Other features of interest on paid ngrok plans include:
- You can use custom sub-domains instead of the randomly generated ngrok subdomains. And such sub-domains can be host in ngrok for as long as you want.
- You can use your own custom domains, which are mapped by ngrok to your local computer.
- And many more…
For a detailed analysis of what ngrok can do, check out the official documentation @ ngrok documentation.
I hope you enjoyed trying out ngrok.
You can check out my other tutorials here.