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. You'll need a few things to get started.

1. An ngrok account

Sign up now for free.

2. The ngrok agent

Find all the options on our downloads page.

3. A local application or API

Accessible on a URL like


http://localhost:8080.

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.

ngrok help

Step 1: Connect your account​

Next, connect your ngrok agent to your ngrok account.

Head over to your ngrok dashboard and click Copy to get your authtoken.

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

ngrok config add-authtoken <NGROK_AUTHTOKEN>

The Setup & Installation page in the dashboard also provides a configuration command specific to your account.

Step 2: Put your app or API online​

Start the ngrok agent with the following command, replacing 8080 with a different port based on where your service lists for traffic.

ngrok http 8080

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

ngrok                                                                                                                                        (Ctrl+C to quit)

Session Status                online
Account                       Foo Bar (Plan: All)
Version                       3.18.4
Region                        United States (California) (us-cal-1)
Latency                       37ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://<GENERATED_NGROK_DOMAIN> -> http://localhost:8080

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

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

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

Step 3: Always use the same domain​

If you want to keep the same URL each time you use the ngrok agent, 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 with your new domain:

ngrok http 8080 --url <YOUR_NGROK_DOMAIN>

Step 4: Write your first Traffic Policy rules​

You may not want anyone to be able to access your app or API on your even though you've made it publicly available. With ngrok, you can add authentication and other traffic management rules, without making any changes to your service, using our Traffic Policy engine.

TK TK TK

Add authentication with OAuth or basic auth​

Let's say you want to restrict access only to you and your coworkers by requiring a successful OAuth log-in with Google, denying anyone who tries to login using an email that doesn't belong to your company's domain name.

Create your first Traffic Policy rule by creating a new file called auth.yaml and add the following YAML to it, replacing <YOUR_DOMAIN> with the domain name you'd like to require.

---
on_http_request:
  - name: "Add Google-based OAuth"
    actions:
      - type: oauth
        config:
          provider: google
  - name: "Restrict OAuth to my domain"
    expressions:
      - "!actions.ngrok.oauth.identity.email.endsWith('<YOUR_DOMAIN>')"
    actions:
      - type: deny

This Traffic Policy rule:

  1. Uses the OAuth action to require you to log in with a Google email.
  2. Checks whether the Google email used to log in does not match your domain name.
  3. Denies all requests that do not match.
  4. Allows all requests that have authenticated with a trusted Google email account.

Now you can run ngrok again using the --traffic-policy-file flag and your file.

ngrok http 8080 --url <YOUR_NGROK_DOMAIN> --traffic-policy-file auth.yaml

Anyone accessing your public endpoint will be prompted to log in with Google and only your account will be allowed to access it.

If you don't have a Google account or you want a simpler form of authentication, you can protect your app with the basic authentication action using a username and password.

---
on_http_request:
  - actions:
      - type: "basic-auth"
        config:
          credentials:
            - "user:password1"

Run your ngrok agent again:

ngrok http 8080 --url <YOUR_NGROK_DOMAIN> --traffic-policy-file auth.yaml

If you access your endpoint with a browser, it'll prompt you for the username and password. If you're putting an API service online and try to access it with curl, you'll get a 401 Unauthorized response unless you base64 encode user:password1 and add the result as a header:

curl --request GET \
  --url http://<YOUR_NGROK_DOMAIN>/ \
  --header 'Authorization: Basic ...`'

ngrok supports many forms of authentication, including:

Step 5: Run 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.