How to demo your localhost app using ngrok

maxcell profile image Prince Wilson Originally published at blog.clarifai.com on ・3 min read

Ngrok is a reverse proxy that allows you to expose your locally running web service to other developers. It’s a timesaver for developers when it comes down to showcasing a project. Follow along and learn how you can put this into your toolbelt of applications!

Howdy everyone! Have you ever wanted to showcase an amazing project that you built at a hackathon; or show a client the progress of the app you’re building without deploying it to some server? A reverse proxy tool like ngrok can solve this. Let’s see how it works.

The Sample App

We’ll need to start with a server running locally. If you don’t have a web app to test you can use a quick Sinatra “Hello, World”:

# app.rb
require 'sinatra'

get '/' do
  'Hello World!'

We need to make sure to have the Sinatra gem. Install the gem through Terminal using:

$ gem install sinatra

To run our app, go into Terminal and write:

$ ruby app.rb

And BOOOM!! 3-line Hello World app.


Ngrok is a tool made by Alan Shreve, who built it to be as accessible as possible by breaking it down into 3 painless steps:

  1. Download ngrok for your OS
  2. Unzip it
  3. Launch it!

Ta-dah! You’re a natural!

Here we will launch ngrok through both macOS/Linux and Windows. Let’s move the executable from my Downloads to our Home folder (marked as the tilde or ~) for our macOS/Linux friends. Open up a new terminal and write:

$ mv /your/path/to/ngrok ~

For Windows we are moving the ngrok.exe to my particular User directory. Mine is called Administrator but yours could be your name (i.e. “Prince Wilson”).

$ move \your\path\to\ngrok \Users\<PC_Name>

We are going to execute ngrok straight from our current directory. In macOS you prepend a script with a ‘./’ to make it execute and in Windows you would use ‘.\’. Otherwise your Terminal will look for ngrok in your PATH. ngrok requires at least two fields: 1) the protocol (i.e. HTTP) and 2) the port we want to expose. If you are running your own app pop in the port it’s using otherwise Sinatra defaults to port 4567.

$ ./ngrok http 4567

$ .\ngrok http 4567

It fires up with a bunch of outputs but we only care about the forwarding url right now. Mine is  “http://da0dcb04.ngrok.io” or “http://f4fcf6f0.ngrok.io”. Notice that it points to where our sample server is, meaning anyone who hits our link will be forwarded to our sample app!


And with that, you have learned the basics of ngrok. But, there is so much more to learn! Try these to improve your experience:

  • To inspect the traffic coming through and replay requests check out http://localhost:4040. Learn more about that in the ngrok documentation.
  • Sign up for an ngrok account if you want to use your own Basic Authentication. What’s there to lose?
  • There are a ton of neato burrito things you can also get out of supporting the project so  pony up if you have the funds to help the software grow.

If you have any questions or want to share your experience with ngrok feel free to send me a note over at hackers@clarifai.com; I’d love to hear from you!


Editor guide
swizzard profile image

Thanks for letting me know. I'm personally very uncomfortable directing potentially sensitive/private traffic through a closed-source tool--there's no guarantee something underhanded won't be done with my data.

ben profile image
Ben Halpern

Been using ngrok for a while and love it.

jakedohm_34 profile image
Jake Dohm

Cool post, Prince!

Ngrok is also built into Laravel Valet (which is a "minimalist dev environment") so all you have to do is run valet share to fire up a quick public URL.

I also was excited to learn (from the comments) that you could password protect the site, and use a private domain for sharing.

swizzard profile image

is ngrok open source?

marcuzy profile image
Oleg Krasavin

There are such tools on npm which you can host on your own server

sammyisa profile image
Sammy Israwi

When making requests from your application, are they made from localhost or from the address ngrok gives you?

marcuzy profile image
Oleg Krasavin

Definitely, your app is going to make a request from your own ip address. ngrok just creates a websocket connection between your local machine and ngrok's server. Every time, when someone requests your subdomain.ngrok.com, ngrok's server emit the request data through the websocket connection. Ngrok's client receives the data and requests corresponding localhost resource. That's to say, your application isn't linked to ngrok and knows nothing about it.

swizzard profile image

They can say that, but without access to their source code how can anyone be sure? It just seems very odd to me that a piece of software targeted at developers would be closed-source.

Thread Thread
maurycyszmurlo profile image
Maurycy Szmurlo

There is neither no any insurrance that the open-source code shown on the repo is the one running on the server...

bdzanis profile image
Anis Bdz

Localtunnel is good alternative

marcuzy profile image
Oleg Krasavin

Yes, it's good one, but also it's quite unstable and slow

maxcell profile image
Prince Wilson Author

Hey Paritosh! I appreciate that catch! Do you happen to know why the above wouldn't work before?

maxcell profile image
Prince Wilson Author

I will make sure to put an edit out and have other people know about the same thing. Thanks again for reading and for letting me know about the issue!