Skip to main content

Quickstart

This quickstart will use the ngrok agent to put your application on the internet and secure it so that only you can access it. It assumes you already have your own application running locally.

1. Install ngrok​

Loading…

Or download the ngrok agent from our Download page if you can't use one of the options above.

Going to the Setup & Installation page in the dashboard will also provide installation directions and commands specific to your platform.

The ngrok agent is a zero-dependency CLI program that runs on all major operating systems. Test that you installed it correctly by running the following command in your terminal and confirm that ngrok prints its help text.

Loading…

2. Connect your account​

Next, connect your ngrok agent to your ngrok account. If you haven't already, sign up for an ngrok account. Copy your ngrok authtoken from your ngrok dashboard.

Run the following command in your terminal to install the authtoken and connect the ngrok agent to your account.

Loading…

Going to the Setup & Installation page in the dashboard will also provide a configuration command specific to your account.

3. Put your app online​

Start ngrok by running the following command.

Loading…

We're assuming that you have a working web application listening on http://localhost:8080. If your app is listening on a different URL, change the above command to match.

You will see something similar to the following console UI in your terminal.

Loading…

Open the Forwarding URL in your browser and you will see your web application.

  • This URL is available to anyone on the internet. Test it out by sending it to a friend!
  • Your app is available over HTTPS (notice the 🔒 in your browser window) with a valid certificate that ngrok automatically manages for you.

4. Always use the same domain​

If you want to keep the same URL each time you use ngrok, create a static domain on your dashboard and then use the --url flag to ask the ngrok agent to use it. First, stop ngrok with Ctrl+C and then run ngrok again:

Loading…

5. Secure your app​

You may not want everyone to be able to access your application. ngrok can quickly add authentication to your app without any changes.

In general, Traffic Policy is the recommended way to secure your app.

When you restrict access to your app using Traffic Policy and Google OAuth, first your users will have to authenticate with Google, then your traffic policy will grant them access based on the rules you configure.

This example uses ngrok's default managed google application to authenticate users. To configure your own Google OAuth application, see the Google OAuth guide.

Loading…

ngrok supports many forms of authentication including:

Running ngrok Persistently​

While this guide gets you started with ngrok, you might want your tunnel to keep running even after you close your terminal window. Here are a few options to achieve this:

  • Using Docker: Docker allows you to containerize ngrok for easy deployment and management. See the documentation for Docker configuration.

  • Systemd service (Linux): For systemd-based systems, you can create a systemd service to automatically start and manage ngrok. Refer to the documentation for Systemd service creation.

  • Windows service (Windows): For Windows systems, you can create a Windows service to automatically start and manage ngrok. Refer to the documentation for Background Service.

  • Detaching a Tmux session (optional): If you're familiar with Tmux, you can detach your ngrok session from your terminal window. (Note: This is an advanced option). Refer to a guide on using Tmux for more information:

What's next?​

Have more questions not answered here?

Reserve your spot in our monthly Office Hours sessions, where you can have your questions about using ngrok answered live by folks in our Developer Education and Product teams, and learn about production use cases alongside your fellow engineers.