One of the frustrations of writing Web or mobile applications is that before you can demo them you must deploy them. For many apps, deployment takes nearly as much work as writing them! Imagine having an ASNA Visual RPG Web app, or an ASNA Mobile RPG app, in Visual Studio on your desktop and, in about 20 seconds, being able to show it to anyone, anywhere, on the Internet. Without deploying it!

That’s right. No deployment. No hassles. Just enter a DOS command in a DOS box and boom, point your browser to the URL provided and your otherwise desktop-bound Web or mobile app is on the Internet for senior management, customers, or other team members to quickly see and use. That’s what ngrok does. It’s amazing. Oh, and it’s cross-platform and it’s free. (The name, I assume, is inspired by Robert A. Heinlein.)

Using ngrok

It is ridiculously easy to use ngrok. Download the executable for your platform, unzip it, and run it. There is no other installation. For convenience, be sure to locate the executable somewhere in your PC’s path.

Open an AVR Web, Wings or Mobile RPG project in Visual Studio and run it using Visual Studio’s intrinsic Web server. Take note of the port in the URL. For example, let’s say your URL looks like this:

the port number is the number immediately after the colon. In this case, the port number is 50490.

Leave the application running in your desktop browser and open a DOS command window. Type in this command line:

ngrok http 50490 --host-header="localhost:50490"

taking care to get the port specified correctly in both places. The --host-header argument is critical–it’s the key to ngrok working with VS/IIS Express. ngrok will display a public HTTP URL and a public HTTPS URL at which your app is now available on the Internet (as shown below):

In this case, the HTTP URL is

http://32b324a1.ngrok.io

and the HTTPS URL is the same but prefixed with HTTPS. Using either of the two URLs provided, anyone on the Internet can now use your app just as if had been deployed on a public-facing Web server. Read about ngrok's other configure features.

Make it easy with a batch file

To make it easy to start ngrok, create a batch file named grok.bat with this line:

ngrok http %1 -host-header="localhost:%1"

With this batch file available in your path you only need to type:

grok <port>

to start ngrok for your localhost Visual Studio projects.

ngrok considerations

  • ngrok is not for production work! Don’t be silly with it.

  • Your app must be running on your local PC at the port specified for the ngrok URL to work. Ending your local instance of the project stops the app.

  • ngrok generates a unique, session-specific URL for a given port each time a ngrok session is started. The ngrok URL doesn’t persist beyond your current session.

  • ngrok is for all intents and purposes an authorized man-in-middle attack. Anyone who knows, or can guess, the URL can use your app while the ngrok URLs are active. However, ngrok does allow protecting URLs with a user ID and password. With care, you can generally count on ngrok's security feature to keep your HTTP tunnel secure. Despite this low risk, beware if you're a shop that is governed by HIPPA, FERPA, other similar regulations.

  • ngrok does a byte-for-byte redirect of Web requests and responses so it’s likely to slow things down a bit. In my seat-of-the-pants use of ngrok, performance impact is negligible.

  • ngrok URLs might look a little scary to customers or others who might doubt your sincerity. Solving that problem is up to you and your good will. There are paid ngrok plans (starting at $60 US) which provide custom subdomain names and reserved domain names.

  • The free ngrok plan provides 40 connections per minute. That sounds like plenty but when using ngrok with a single-page app making lots of Ajax requests, I hit the request limit a couple of times. The $96 annual plan bumps this limit to 120 connections per minute.

  • ngrok's HTTPS option is quite helpful. For example, you can't use the geolocation API on Google Chrome unless you're using HTTPS. ngrok makes it easy to test APIs with an HTTPS dependency. 

Special thanks

I came across ngrok several months ago but wasn’t smart enough to make it work with Visual Studio and IIS Express. But ASNA’s R&D engineer extraordinaire, Jorge Contreras, recently showed me ngrok’s --host-header option–which is the trick to ngrok working with VS/IIS Express. Thanks for the help, Jorge!