Skip to main content

ngrok Agent CLI Quickstart

ngrok's core functionality is built around Agent Endpoints: ephemeral tunnels that connect your locally running apps to the internet through the ngrok cloud service. 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. An ngrok account.
  2. Your ngrok auth token, which you can find in the dashboard.

1. Reserve your domain​

A new URL is generated for you every time you start an agent endpoint. To maintain a consistent URL, you can reserve a free static domain connected to your ngrok account.

To do so, navigate to the dashboard, visit the Domains section, and select + New Domain. You can choose a free static domain, or you can use a custom domain you already own. We'll come back to this in later steps.

2. Install the ngrok Agent CLI​

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

Loading…

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.

Loading…

3. 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.

Loading…

4. 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.

Loading…

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

5. Put your app online​

Start the ngrok agent by running the following command (replace 8080 if your app is running on a different port). The optional --url flag connects your app to your reserved domain from step 1—replace $YOUR_DOMAIN with this.

Loading…

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.

6. 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 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:

Loading…

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.

Loading…
tip

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:

Loading…

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 ephemeral endpoints repeatable and scalable by assigning a name you can refer back to with URLs, protocols, and actions already defined.

  • 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 that isn't tied to the ephemeral lifetime of an agent endpoint, you should proceed to getting started with Cloud Endpoints.
  • This quickstart only 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.