Skip to main content
ngrok’s core functionality is built around Agent Endpoints: endpoints that connect your locally running apps to the internet through the ngrok cloud service and are only available as long as the agent is running somewhere. Common use cases include granting remote access to IoT devices, enabling your Kubernetes clusters to communicate with each other, and allowing external connections to a local gaming server. 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

​
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
brew 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}`);
});
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.
ngrok.yml
endpoints:
  - name: cli-quickstart
    url: $YOUR_DOMAIN
    traffic_policy:
      on_http_request:
        - actions:
          - type: oauth
            config:
              provider: google
    upstream:
      url: 8080
      protocol: http1
This example uses ngrok’s default Google OAuth application. To use your own, see the OAuth Traffic Policy Action documentation.
Now you can start up your endpoint using its name: 
ngrok start cli-quickstart
When you visit your public URL you should be prompted to authenticate by logging in with a Google account before you can access your app.

​
What’s next?

In this guide, you learned how to create an agent endpoint to forward traffic from the internet to an app running on your local device using the ngrok agent CLI. You were introduced to some of the most common commands you should know, and you implemented a traffic policy, which can be used for many kinds of actions beyond the basic authentication example here. You also saw how to edit your config file to make your agent endpoints repeatable and scalable by assigning a name you can refer back to with URLs, protocols, and actions already defined. What else can you do with these features?
  • If you need to interact with ngrok agent endpoints programmatically, we recommend using one of our Agent SDKs which are available for JavaScript (Node.js), Go, Python, and Rust.
  • If your use case calls for a centrally managed, always-on endpoint instead of one that is only available when an agent is running, you should proceed to getting started with Cloud Endpoints.
  • This quickstart barely scratches the surface of what’s possible with a traffic policy—check out the Actions overview to see what else you can do.
  • Visit the Agent CLI command reference for a complete list of available commands.