Local Tunneling Quickstart Guide

ngrok is a software-defined network edge fronting your web service running on your local machine. Follow these steps to create a tunnel to an application and safely expose it to the outside.

Downloading the ngrok Agent

The ngrok agent is the command line application that you will use to start your tunnels. Download the correct build for your operating system from the ngrok download page. Selecting More Options will show you all the latest builds.

Once the ngrok agent downloads, unzip the file from your Downloads folder into a location referenced in your PATH environment variable. For instance, on Linux or MacOS a common location would be /usr/local/bin and on Windows a common location is C:\User\<name>\Local\Bin. On Linux or MacOS you can you can see the value of your PATH environment variable by running the command:

echo $PATH

On Windows, use the command:

echo %PATH%

On Linux or MacOS, unzip ngrok:

sudo unzip -d /usr/local/bin/ <filename>

On Windows, right-click the downloaded file and extract to:

C:\User\<name>\Local\Bin

Fire Up ngrok

Start the terminal application directly, and try running the ngrok command.

You should see the help text followed by another command prompt. If you see that you can run further ngrok commands.

Troubleshooting Tip: If you do not see the help text followed by another command prompt, a common reason is the ngrok file isn't in a very accessible location in your file system. Return to the step above to find a location referenced on your $PATH environment variable and make sure you have unzipped the ngrok file there.

Now try starting an http tunnel to test out ngrok's functionality. You can start an HTTP tunnel to port 8080 by running the command:

ngrok http 8080

Then, copy the URL that the ngrok agent generated for your tunnel.

Paste this URL into your browser. You should see a 502 error since we don't actually have an application running on port 8080 yet.

Tunneling to Your Application

Previously, you started a tunnel but didn't have any application running. Start your application and note the port that your server is using. For our example we are serving static content from a directory on port 8080 using Python's http.server module.

$ python -m http.server --directory demo/content/dir 8080

Return to your terminal and use this command to start a tunnel to your port.

ngrok http 8080

Then, copy the URL that the ngrok agent generated for your tunnel and paste it into your browser to view your application.

Create an ngrok Account

Your tunnels will expire after a short period of time unless you sign up for an account and add your authtoken to your ngrok agent. Sign up for an ngrok account here.

We'll send you a verification email. You'll need to click the link in the email to verify your account.

Adding your Account Authtoken to your ngrok Agent

When you created your ngrok account we issued you a unique authtoken. Navigate to your ngrok account dashboard. Select Your Authtoken from the sidebar menu. Copy your authtoken.

Then open your terminal and paste your authtoken into the following command:

ngrok authtoken <your authtoken>

You should see a message confirming your authtoken has been added to your ngrok.yml configuration file:

Now your tunnels will run indefinitely or until you stop them yourself!

ngrok Traffic Inspector

You can make a request and view any traffic passing through your tunnel using the ngrok traffic inspector at http://localhost:4040.

That's it, but there's lots more you can do with ngrok! Learn more in our documentation.