Developers: Have you ever worked on a codebase that required Oauth 2.0? Or maybe your code used a third-party service that would only work on a verified public domain. “That won’t work on my local environment,” you say. “I guess we’ll test it in production.” Wouldn’t it be nice if you could magically have a public domain for your local machine?

Enter ngrok. With a single command line instruction, you can connect your local code to a secure public domain for free. Now you can test Oauth, run your integrations and even send a link to your project (running on your local machine) to your client. Pretty neat! I’ll show you how to do it.

1. Setup

Start by downloading the zipped executable here. Unzip. Add the executable to your system PATH if you’d like. You can now run the command ngrok (or on Windows, ./ngrok).

I placed my executable in my ~/code/ directory and got this output:

2. Prepare Codebase

For this example, I pulled a fresh installation of Laravel to my local machine, set up Apache and created a virtual host called voyager-test.com. When I navigate to http://voyager-test.com, of course I see the Laravel splash page:

3. Run ngrok

Now it’s time for some magic. On the command line, run ngrok http 80 -host-header=voyager-test.com (./ngrok http 80 -host-header=voyager-test.com on Windows). ngrok will run and listen.

You can kill it with CTRL+C like any other listening process.

Now navigate to http://localhost:4040. You’ll get your ngrok dashboard where your public domain will be listed.

Notice that you only get the domain for eight hours using the free account. Click on the domain (I prefer to use the HTTPS version) and take a look:

There you have it! You can send this website to a client for review, share it with a coworker or check it out on your phone.

ngrok will monitor domain requests to your website on its dashboard and provide some useful information for you.

Bonus: Connecting to Virtual Machines

Let’s say you develop using a VM. (I tend to use Laravel Homestead.) No problem! Set up ngrok so your VM is accessible by your public domain.

If you’re not familiar with Homestead, you can learn how to set up vagrant, clone Homestead and set up your configuration from the Laravel docs. My Homestead.yaml file looks like this:

---
ip: "192.168.10.10"
memory: 4096
cpus: 4
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
- ~/.ssh/id_rsa

folders:
- map: ~/code
to: /home/vagrant/code
type: "nfs"

sites:
- map: test.app
to: /home/vagrant/code/test/public

databases:
- test

This sets up a virtual box at 192.168.10.10 which maps my code in /home/vagrant/code/test/public to the domain test.app. It also creates a database called test. If I navigate to my Homestead folder and type vagrant up the box will start. I create a file at /home/vagrant/code/test/public/index.html with the contents My test website. Now if I navigate to test.app on my machine I see:

Now time for ngrok. Type in ./ngrok http 192.168.10.10:80 -host-header=test.app. Run this outside of the vagrant box (don’t ssh in and try to run it from inside).

Navigate to localhost:4040 to get the ngrok dashboard. Click on the new public domain.

Amazing! A public website hosted from your Homestead VM on your local development machine.