> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent CLI Quickstart
> Learn how to get started with ngrok Agent CLI to create secure tunnels from your local applications to the internet.
Complete the ngrok Agent CLI quickstart on my machine:
1. Install the ngrok Agent CLI for my operating system
2. Connect my ngrok account by running `ngrok config add-authtoken ` — ask me for the token
3. Start a minimal HTTP server on port 8080 in whatever language is easiest
4. Expose it publicly: `ngrok http 8080`
5. Secure it with Google OAuth by editing ngrok.yml to add a traffic policy
6. Restart with `ngrok start cli-quickstart` and confirm a login prompt appears
Ask me for my auth token and reserved domain before starting.
The simplest way to get started is to create an Agent Endpoint that forwards public traffic to your localhost using the [ngrok Agent CLI](/agent/).
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](https://dashboard.ngrok.com/signup).
* Your [ngrok auth token](https://dashboard.ngrok.com/get-started/your-authtoken).
* On Mac OS, you'll need [homebrew](https://brew.sh/).
## 1. Install the ngrok Agent CLI
Run the command that corresponds to your operating system to install the Agent CLI:
Install ngrok via [Homebrew](https://brew.sh/).
```bash theme={null}
brew install ngrok
```
```bash theme={null}
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
```
Install via the Windows App Store
Or [follow the direct installation guide](https://download.ngrok.com?tab=download) 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.
```bash theme={null}
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](https://dashboard.ngrok.com/get-started/your-authtoken).
```bash theme={null}
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`.
```javascript title="service.js" theme={null}
const http = require('http');
const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/html' });
const html = `
Test Page
Hello from Node.js HTTP Server!
`;
res.end(html);
});
const port = 8080;
server.listen(port, () => {
console.log(`Serving custom HTML at http://localhost:${port}`);
});
```
```go title="service.go" theme={null}
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)
}
}
```
```python title="service.py" theme={null}
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"""
Test Page
Hello from Python HTTP Server!
"""
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).
```bash theme={null}
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](/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`:
```bash theme={null}
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.
```yaml title="ngrok.yml" theme={null}
endpoints:
- name: cli-quickstart
url: $YOUR_DOMAIN
traffic_policy:
on_http_request:
- actions:
- type: oauth
config:
provider: google
- expressions:
- "!actions.ngrok.oauth.identity.email.endsWith('@acme.com')"
actions:
- type: deny
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](/traffic-policy/actions/oauth/#google-example).
Now you can start up your endpoint using its name:
```bash theme={null}
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, use one of the Agent SDKs which are available for [JavaScript (Node.js)](/getting-started/javascript/), [Go](/getting-started/go/), [Python](/getting-started/python/), and [Rust](/getting-started/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](/getting-started/cloud-endpoints-quickstart/).
* This quickstart barely scratches the surface of what's possible with a Traffic Policy—check out the [Actions overview](/traffic-policy/actions/) to see what else you can do.
* Visit the [Agent CLI command reference](/agent/cli/) for a complete list of available commands.