Share Localhost Quickstart

The simplest way to get started is to create an Agent Endpoint that forwards public traffic to your localhost using the ngrok Agent CLI. This quickstart walks you through that process, as well as how to implement basic security measures by requiring visitors to log in with a Google account to access your app.

What you’ll need

An ngrok account.
Your ngrok auth token.
On Mac OS, you’ll need homebrew.

1. Install the ngrok Agent CLI

Run the command that corresponds to your operating system to install the Agent CLI:

Mac OS
Debian Linux
Windows

Install ngrok via Homebrew.

brew install ngrok

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update \
  && sudo apt install ngrok

Or follow the direct installation guide if you can’t use one of the options above. To test that it’s been installed correctly, run the following command in your terminal and confirm that ngrok prints its help text.

ngrok help

2. Connect your account

Connect your agent to your ngrok account by providing your auth token as shown below—replace $YOUR_TOKEN with the string given to you in the dashboard.

ngrok config add-authtoken $YOUR_TOKEN

3. Start your app or service

Start up the app or service you’d like to put online. This is the app that your Agent Endpoint will forward online traffic to. If you don’t have an app to work with, you can create a minimal app in your language of choice using the following code to set up a basic HTTP server at port 8080.

const http = require('http');

const server = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    const html = `
    <html>
    <head><title>Test Page</title></head>
    <body><h1>Hello from Node.js HTTP Server!</h1></body>
    </html>
    `;
    res.end(html);
});

const port = 8080;
server.listen(port, () => {
    console.log(`Serving custom HTML at http://localhost:${port}`);
});

package main

import (
	"fmt"
	"net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello from Go HTTP Server!")
}

func main() {
	http.HandleFunc("/", handler)

	fmt.Println("Starting server at http://localhost:8080")
	err := http.ListenAndServe(":8080", nil)
	if err != nil {
		fmt.Println("Server failed:", err)
	}
}

from http.server import BaseHTTPRequestHandler, HTTPServer

class MyHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header("Content-type", "text/html")
        self.end_headers()
        html = b"""
        <html>
        <head><title>Test Page</title></head>
        <body><h1>Hello from Python HTTP Server!</h1></body>
        </html>
        """
        self.wfile.write(html)

def run(server_class=HTTPServer, handler_class=MyHandler, port=8080):
    server_address = ('', port)
    httpd = server_class(server_address, handler_class)
    print(f"Serving custom HTML at http://localhost:{port}")
    httpd.serve_forever()

if __name__ == "__main__":
    run()

Navigate to the directory where this file is located and start the server.

4. Put your app online

Start the ngrok agent by running the following command (replace 8080 if your app is running on a different port).

ngrok http 8080

All accounts come with a free dev domain that is automatically chosen when you start an endpoint. You can add the optional --url flag to customize this domain on paid plans.

The agent should print a console UI to your terminal to confirm that it’s online and forwarding as intended. Open the forwarding URL in your browser to see your web application, which is now available over HTTPS with a valid certificate that ngrok automatically manages for you.

5. Secure your app

ngrok makes it simple to add authentication to your app by implementing a Traffic Policy. Using the Agent CLI, you can add a Traffic Policy to your endpoint by editing your ngrok config file, which was automatically created when you provided your auth token in step 3. Terminate the Agent Endpoint that you started up in step 5, then run the following command in your terminal to open ngrok.yml:

ngrok config edit

You should see a new console UI with your config version and auth token already set. Below the auth token, paste the following snippet into the editor and then save and exit the config file. This policy states that whenever an HTTP/S request is made to $YOUR_DOMAIN, the Agent Endpoint should redirect the user to Google OAuth for authentication before proceeding to the app running on port 8080. If the email is not from the specified domain, in this case @acme.com, the visitor will be denied access.

ngrok.yml

endpoints:
  - name: cli-quickstart
    url: $YOUR_DOMAIN
    traffic_policy:
      on_http_request:
        - actions:
            - type: oauth
              config:

Use Cases

Concepts

Identity & Access

What you’ll need

1. Install the ngrok Agent CLI

2. Connect your account

3. Start your app or service

4. Put your app online

5. Secure your app

​What you’ll need

​1. Install the ngrok Agent CLI

​2. Connect your account

​3. Start your app or service

​4. Put your app online

​5. Secure your app

What you’ll need

1. Install the ngrok Agent CLI

2. Connect your account

3. Start your app or service

4. Put your app online

5. Secure your app