> ## 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 Config Version 3
> Reference documentation for ngrok Agent Configuration File version 3, including breaking changes, migration guide, and endpoint definitions.
The ngrok agent supports an optional, YAML configuration file which enables you to configure advanced settings and run multiple endpoints simultaneously.
The agent configuration file location depends on your system. You can check the location of your configuration file by running `ngrok config check` or edit the file in your terminal by running `ngrok config edit`.
YAML is whitespace-sensitive.
Use spaces only (tabs are not valid in YAML) and keep keys at the same level aligned to the same column.
✅ Valid:
```yaml theme={null}
endpoints:
- name: example
upstream:
url: 80
```
❌ Invalid—`upstream` is indented inconsistently and will fail to parse:
```yaml theme={null}
endpoints:
- name: example
upstream:
url: 80
```
## Breaking changes
There are important differences between the v3 ngrok Agent Configuration file and v2:
* Agent configuration options are no longer top-level, they are now nested under the `agent` field.
* Endpoints are now configured through the `endpoints` field.
* Deprecated the `tunnels` field in favor of [`endpoints`](#endpoint-definitions).
* Changed `server_addr` agent configuration field to [`connect_url`](#connect-url).
* Changed `root_cas` agent configuration field to [`connect_cas`](#connect-cas).
* Labeled tunnels are no longer supported in v3. Use [endpoints](/api-reference/endpoints/list) instead.
## Migrating from v2
Migrating from v2 to v3 requires you to update to the latest agent, nest your agent configuration
options under the `agent` field and change the `version` field to `3` as well as modify any [agent
configuration fields that have changed](#breaking-changes).
For example, here is an example v2 configuration file:
```yaml theme={null}
version: 2
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN
tunnels:
basic:
proto: http
addr: 80
```
For v3, you need to update the `version`, introduce the `agent` field,
and convert from `tunnels` to `endpoints`:
```yaml theme={null}
version: 3
agent:
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN
endpoints:
- name: http
url: http://demo.ngrok.app
upstream:
url: 80
```
You will also need to adjust the following fields if you are using them:
* Change `root_cas` to `connect_cas`
* Change `server_addr` to [`connect_url`](#connect-url)
## Supported fields
The ngrok Agent Configuration file supports the following top-level configuration fields:
* [Configuration File Version Field](#version) - `version` (required)
* [Agent Configuration Field](#agent-configuration) - `agent` (required)
* [Endpoint Definitions](#endpoint-definitions) - `endpoints`
* [Tunnel Definitions](#tunnels-deprecated) - `tunnels` (deprecated)
## Version
The top-level `version` field is **required**. Value **must** be `3`.
### Example
```yaml theme={null}
version: 3
```
## Agent configuration
The top-level `agent` field is **required**. The agent field allows you to modify both general and advanced agent configuration options, everything from your authtoken to whether the agent should check for updates.
### Agent configuration options
| Name | Description |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`api_key`](#api-key) | The API key to be used when making requests through the `ngrok api` command. |
| [`authtoken`](#authtoken) | The authentication token used to authenticate this agent when it connects to the ngrok service. |
| [`connect_cas`](#connect-cas) | The root certificate authorities used to validate the TLS connection to the ngrok server. |
| [`connect_interface`](#connect-interface) | Set the specific network interface for ngrok to use. This is only supported on Linux platforms. |
| [`connect_timeout`](#connect-timeout) | How long to wait when establishing an agent session connection to the ngrok service. The default is 10s. |
| [`connect_url`](#connect-url) | This is the URL of the ngrok server to connect to. You should only set this if you are using a custom ingress URL. |
| [`console_ui`](#console-ui) | Enable/disable the console UI |
| [`console_ui_color`](#console-ui-color) | Set the background color of the console UI |
| [`crl_noverify`](#crl-noverify) | Disables verifying Certificate Revocation List |
| [`dns_resolver_ips`](#dns-resolver-ips) | Consult these DNS servers for tunnel session DNS resolution. |
| [`heartbeat_interval`](#heartbeat-interval) | How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. Default is 10s. |
| [`heartbeat_tolerance`](#heartbeat-tolerance) | Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. Default is 15s. |
| [`inspect_db_size`](#inspect-db-size) | The size in bytes of the upper limit on memory to allocate to save requests over HTTP tunnels for inspection and replay. |
| [`log_level`](#log-level) | Logging level of detail. In increasing order of verbosity, possible values are: `crit`, `warn`, `error`, `info`, and `debug`. |
| [`log_format`](#log-format) | Format of written log records. |
| [`log`](#log) | Write logs to this target destination. |
| [`metadata`](#metadata) | Opaque, user-supplied string that will be returned as part of the ngrok API response to the [list online sessions](/api-reference/tunnelsessions/list) resource for all endpoints started by this agent. |
| [`proxy_url`](#proxy-url) | URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection. |
| [`remote_management`](#remote-management) | Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update). Defaults to `true`. |
| [`update_channel`](#update-channel) | The update channel determines the stability of released builds to update to. Use `stable` for all production deployments. |
| [`update_check`](#update-check) | This tells the ngrok agent if it should check for updates. Defaults to `true`. |
| [`web_addr`](#web-addr) | Network address to bind on for serving the local web interface and api. |
| [`web_allow_hosts`](#web-allow-hosts) | `Host` headers to allow access for on the local web interface and api, can be a combination of IP's, CIDR ranges, and/or hostname suffixes. |
#### `authtoken`
The authentication token used to authenticate this agent when it connects to the ngrok service. You can obtain your default authtoken through the [ngrok Dashboard](https://dashboard.ngrok.com/get-started/your-authtoken).
##### Deploying on multiple devices
Your default authtoken will work on multiple machines or devices. However, if you want more control and security across many devices, you can generate a unique authtoken for each device in the [ngrok Dashboard](https://dashboard.ngrok.com/tunnels/authtokens) or via the `ngrok api credentials` command.
##### Example
```yaml {2,2} theme={null}
agent:
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
```
#### `api_key`
This option is only required when you want to make requests using the `ngrok api` command and should not be confused with the `authtoken` option.
The API key to be used when making requests through the `ngrok api` command. You can obtain and manage your API Keys through the [ngrok Dashboard](https://dashboard.ngrok.com/api-keys).
##### Example
```yaml {2,2} theme={null}
agent:
api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN
```
#### `connect_cas`
This is the root certificate authorities used to validate the TLS connection to the ngrok server.
| Parameter | Default | Description |
| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trusted` | default | use only the trusted certificate root for the ngrok.com tunnel service |
| `host` | | use the root certificates trusted by the host's operating system. This is helpful for working with machine-in-the-middle (MITM) proxies doing deep packet inspection (DPI). |
| other values | | path to a certificate PEM file on disk with certificate authorities to trust |
| | | |
#### `connect_interface`
Sets the specific network interface that the ngrok agent should use. This is only supported on Linux platforms.
#### `connect_timeout`
How long to wait when establishing an agent session connection to the ngrok service. This is specified as a duration, with the default being 10s.
#### `connect_url`
This is the URL of the ngrok server to connect to. You should set this if you are using a custom Connect URL. See [the Connect URL docs](/agent/connect-url/) for more information.
#### `console_ui`
This option allows you to enable or disable the console UI that is displayed in your terminal window after starting ngrok.
| Parameter | Default | Description |
| --------- | ------- | ---------------------------------------------------------------- |
| `true` | | Enable the console UI |
| `false` | | Disable the console UI |
| `iftty` | default | Enable the UI only if standard out is a TTY (not a file or pipe) |
#### `console_ui_color`
The command sets the background color when displaying the console UI in the terminal. To choose a color other than black, set the value to transparent and change the background of your terminal window.
| Parameter | Default | Description |
| ------------- | ------- | ----------------------------------------------------------- |
| `transparent` | | Don't set a background color when displaying the console UI |
| `black` | default | Set the console UI's background to black |
#### `crl_noverify`
This option will skip verifying with the Certificate Revocation List if set to `true`. This defaults to `false`.
#### `dns_resolver_ips`
Consult these DNS servers for tunnel session DNS resolution. By default, the ngrok agent will use the local system DNS servers to resolve.
#### `heartbeat_interval`
How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. The default is 10s.
#### `heartbeat_tolerance`
Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. The default is 15s.
#### `inspect_db_size`
This is the upper limit in bytes on memory to allocate when saving requests over HTTP endpoints for inspection and reply. The default is 0, which means 50MB.
| Parameter | Default | Description |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| positive integers | | size in bytes of the upper limit on memory to allocate to save requests over HTTP endpoints for inspection and replay. |
| `0` | default | use the default allocation limit, 50MB |
| `-1` | | disable the inspection database; this has the effective behavior of disabling inspection for all tunnels |
#### `log_level`
This is the logging level of detail. In increasing order of verbosity, possible values are: `crit`, `warn`, `error`, `info`, and `debug`.
#### `log_format`
This is the format of written log records.
| Parameter | Default | Description |
| --------- | ------- | -------------------------------------------------------------------------------- |
| `logfmt` | | human and machine friendly key/value pairs |
| `json` | | newline-separated JSON objects |
| `term` | default | custom colored human format if standard out is a TTY, otherwise same as `logfmt` |
#### `log`
This is the destination where ngrok should write the logs.
| Parameter | Default | Description |
| --------- | ------- | -------------------------------------- |
| `stdout` | | write to standard out |
| `stderr` | | write to standard error |
| `false` | default | disable logging |
| `` | | write log records to file path on disk |
```yaml {2,2} theme={null}
agent:
log: /var/log/ngrok.log
```
#### `metadata`
This is a user-supplied custom string that will be returned as part of the ngrok API response to the [list online sessions resource](/api-reference/tunnelsessions/list) for all endpoints started by this agent. This is a useful mechanism to identify endpoints by your own device or customer identifier. Maximum 4096 characters.
```yaml {2,2} theme={null}
agent:
metadata: bad8c1c0-8fce-11e4-b4a9-0800200c9a66
```
#### `proxy_url`
This is the URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection. Many HTTP proxies have connection size and duration limits that will cause ngrok to fail. Like many other networking tools, ngrok will also respect the environment variable `http_proxy` and `http_proxy_env` if it is set.
#### `remote_management`
Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update) via the [ngrok API](/api-reference/tunnelsessions/restart) or the [ngrok Dashboard](https://dashboard.ngrok.com/tunnels/agents). Defaults to `true`.
#### `update_channel`
The update channel determines the stability of released builds to update to. Use 'stable' for all production deployments.
| Parameter | Default | Description |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `stable` | default | These are builds that are ready to be used in production. |
| `unstable` | | update to new nightly builds when available which could be broken. This should not be used in production. |
| `beta` | | update to new beta builds when available which could be broken. This should not be used in production. |
#### `update_check`
This tells the ngrok agent if it should check for updates. Defaults to `true`.
#### `web_addr`
This is the network address to bind on for serving the local agent web interface and API.
| Network address | | Bind to this network address |
| ---------------- | ------- | ---------------------------- |
| `127.0.0.1:4040` | default | default network address |
| `false` | | disable the web UI |
#### `web_allow_hosts`
These are a list of specifiers for what `Host` headers will be allowed to make requests agains the local agent web interface and API. Any port is stripped off the `Host` header before matching is performed.
| Allow string | | Example `Host` headers that would match |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| | default | requests to localhost-bound web interface or API endpoints are checked to have a localhost-like `Host` (localhost, 127.0.0.1, ::1, etc.) |
| `8.8.8.8` | | an IP matches `Host` header (`8.8.8.8`) |
| `1:2:3:4:5:6:7:8` | | an IPv6 matches `Host` header (`1:2:3:4:5:6:7:8`) |
| `10.0.0.0/8` | | a CIDR range matches a `Host` header that is an IP address in that range (`10.0.0.1 or 10.1.2.3`) |
| `1:2:3:4:5:6:7:8/16` | | a CIDR range matches a `Host` header that is an IPv6 address in that range (`1:2:3:4:5:6:7:0`) |
| `example.com` | | a hostname without preceding period will match `Host` header exactly (`example.com`) |
| `.example.com` | | a hostname with a preceding period `Host` header suffix (`sub.example.com` or `foo.example.com`) |
##### Example
Allow an IP address and a domain as `Host` headers:
```yaml {2-4} theme={null}
agent:
web_allow_hosts:
- 8.8.8.8
- example.com
```
### Working with machine-in-the-middle (MITM) proxies
If you're working with machine-in-the-middle (MITM) proxies, you may need to specify a custom CA certificate to trust the ngrok server.
This may require you to use the ngrok root CA certificate that the agent uses to connect to the ngrok edge.
Use the following command to extract the ngrok agent self-signed root CA certificate:
``strings `which ngrok` | grep 'BEGIN CERTIFICATE' -A 22``
This outputs the root CA certificate in PEM format.
## Endpoint definitions
The `endpoints` field enables you to define and configure multiple endpoints.
Defining multiple endpoints this way enables you to start pre-configured endpoints
by name without having to memorize the right arguments every time through the
`ngrok start` command. You can also use this field to start multiple endpoints at
the same time from a single agent using the `ngrok start --all` flag.
The endpoints field accepts a list of endpoint configurations, the list of available
endpoint configuration options can be found here.
### Example
The snippet below defines two HTTPS endpoints, one TCP endpoint, and one TLS endpoint, named 'httpbin', 'demo', 'ssh', and 'demo-2', respectively:
```yaml theme={null}
endpoints:
- name: httpbin
url: https://alan-httpbin.ngrok.app
upstream:
url: 8080
- name: demo
url: https://demo.inconshreveable.com
upstream:
url: 8181
- name: ssh
url: tcp://1.tcp.ngrok.io:12345
upstream:
url: 22
- name: demo-2
url: tls://myexample.ngrok.app
upstream:
url: 443
```
#### Start the endpoint named 'httpbin'
```sh theme={null}
ngrok start httpbin
```
#### Start all endpoints
```sh theme={null}
ngrok start --all
```
### Endpoint configuration options
| Name | Required | Description |
| ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [`agent_tls_termination`](#agent-tls-termination) | | Configuration for TLS termination at the ngrok agent. This is applicable only when the endpoint URL scheme is `tls://`. |
| [`name`](#name) | Required | A unique name for this endpoint's configuration. |
| [`url`](#url) | | The address you would like to use to forward traffic to your upstream service. Leave empty to get a randomly assigned address. |
| [`bindings`](#bindings) | | Allows you to configure the bindings for this endpoint. Currently only one binding may be provided. |
| [`metadata`](#metadata-1) | | An arbitrary string of user-defined metadata for this endpoint. |
| [`description`](#description) | | An arbitrary user-defined description about this endpoint. |
| [`traffic_policy`](#traffic-policy) | | Accepts a Traffic Policy configuration in YAML format. |
| [`upstream`](#upstream) | Required | Upstream service configuration options. |
#### `agent_tls_termination`
Object. Configuration for TLS termination at the ngrok agent. This is applicable only when the endpoint URL scheme is `tls://`.
##### `agent_tls_termination.mutual_tls_certificate_authorities`
String\[]. Specifies one or more Root CA certificates (as paths or raw PEM data) to validate client certificates for mutual TLS authentication. Available only for `tls://` URLs.
##### `agent_tls_termination.server_certificate`
String. The server certificate (provided as a file path or raw PEM data) used by the ngrok agent for TLS termination. Available only for `tls://` URLs.
##### `agent_tls_termination.server_private_key`
String. The private key (provided as a file path or raw PEM data) corresponding to the server certificate, used for TLS termination by the ngrok agent. Available only for `tls://` URLs.
#### `name`
**Required.** String. A unique name for this endpoint's configuration.
This is the value you use when running the `ngrok start ` command.
##### Example
```yaml {3} theme={null}
# ...
endpoints:
- name: example
# ...
```
#### `url`
String\[]. The address you would like to use to forward traffic to your upstream service.
##### Accepted formats:
* **Domain** - `example.org`
* When using the *domain* format you are only defining the domain. The scheme and port will be inferred.
* **Origin** - `https://example.ngrok.app` *or* `https://example.ngrok.app:443` *or* `tcp://1.tcp.ngrok.io:12345` *or* `tls://example.ngrok.app`
* When using the *origin* format you are defining the protocol, domain and port. HTTP endpoints accept ports `80` or `443` with respective protocol.
* **Scheme (shorthand)** - `https://` *or* `tcp://` *or* `tls://` *or* `http://`
* When using *scheme* you are defining the protocol and will receive back a randomly assigned ngrok address.
* **Empty** - \`\`
* When *empty* your endpoint will default to be `https` and receive back a randomly assigned ngrok address.
##### Example
```yaml {4} theme={null}
# ...
endpoints:
- name: example
url: https://example.ngrok.app
# ...
```
#### `bindings`
String\[]. Allows you to configure the bindings for this endpoint. Currently only one binding may be provided.
The allowed values are `internal`, `public`, and `kubernetes` which allow you to create [public](/gateway/public-endpoints/), [internal](/gateway/internal-endpoints/), and [kubernetes endpoints](/gateway/kubernetes-endpoints/).
This field is mainly only truly necessary for creating kubernetes endpoints as the default for all endpoints is to have a `public` binding, and an `internal` binding is automatically inferred when the endpoint URL ends in `.internal`.
To create a kubernetes endpoint (which projects the endpoint into one or more kubernetes clusters running the ngrok Operator as a `Service` resource), set the `bindings` field to `["kubernetes"]`.
##### Example
```yaml {4} theme={null}
# ...
endpoints:
- name: example
url: https://example-service.example-namespace
bindings:
- kubernetes
# ...
```
#### `metadata`
String. An arbitrary string of user-defined metadata for this endpoint. This value will appear on the endpoint object in the ngrok API.
##### Example
```yaml {5} theme={null}
# ...
endpoints:
- name: example
url: https://example.ngrok.app
metadata: '{ "id": "example-app" }'
# ...
```
#### `description`
String. An arbitrary user-defined description about this endpoint. This value will appear on the endpoint object in the ngrok API.
##### Example
```yaml {6} theme={null}
# ...
endpoints:
- name: example
url: https://example.ngrok.app
metadata: '{ "id": "example-app" }'
description: "our example application"
# ...
```
#### `traffic_policy`
Object. Accepts a Traffic Policy configuration in YAML format.
Traffic Policy enables you to manage, route, and secure traffic through configuration.
You can learn more about the individual parts of the Traffic Policy and the available actions here:
* [HTTP Traffic Policy Docs](/traffic-policy/)
* [TLS Traffic Policy Docs](/traffic-policy)
* [TCP Traffic Policy Docs](/traffic-policy)
##### Example
```yaml {7-15} theme={null}
# ...
endpoints:
- name: example
url: https://example.ngrok.app
metadata: '{ "id": "example-app" }'
description: "our example application"
traffic_policy:
on_http_request:
- actions:
- type: custom-response
config:
status_code: 200
body: hello, Traffic Policy!
headers:
content-type: text/plain
# ...
```
#### `upstream`
Object. Upstream service configuration options.
##### `upstream.url`
String. The local or remote address you would like to incoming traffic to be forwarded to.
###### Accepted formats:
* **Origin** - `https://example.org` *or* `http://example.org:80` *or* `tcp://127.0.0.1:80`
* When using the *origin* format you are defining the protocol, domain and port.
* When no port is present and scheme is `https` or `http` the port will be inferred.
* For `https` port will be`443`.
* For `http` port will be `80`.
* **Domain** - `example.org`
* This is only allowed for `https` and `http` endpoints.
* For `tcp` and `tls` endpoints host and port is required.
* When using the *domain* format you are only defining the host.
* Scheme will default to `http`.
* Port will default to `80`.
* **Scheme (shorthand)** - `https://`
* This only works for `https` and `http`.
* For `tcp` and `tls` host and port is required.
* When using *scheme* you are defining the protocol and the port will be inferred on the local host.
* For `https` port will be`443`.
* For `http` port will be `80`.
* Host will be `localhost`.
* **Port (shorthand)** - `8080`
* When using *port* you are defining the port on the local host that will receive traffic.
* Scheme will default to `http`.
* Host will default to `localhost`.
###### Example
```yaml {16-17} theme={null}
# ...
endpoints:
- name: example
url: https://example.ngrok.app
metadata: '{ "id": "example-app" }'
description: "our example application"
traffic_policy:
on_http_request:
- actions:
- type: custom-response
config:
status_code: 200
body: hello, Traffic Policy!
headers:
content-type: text/plain
upstream:
url: 8080
# ...
```
##### `upstream.protocol`
String. The application layer protocol the agent should use when talking to your upstream application for HTTP endpoints.
###### Accepted values:
* `http1` (default)
* `http2`
###### Example
```yaml {18-18} theme={null}
# ...
endpoints:
- name: example
url: https://example.ngrok.app
metadata: '{ "id": "example-app" }'
description: "our example application"
traffic_policy:
on_http_request:
- actions:
- type: custom-response
config:
status_code: 200
body: hello, Traffic Policy!
headers:
content-type: text/plain
upstream:
url: 8080
protocol: http1
# ...
```
##### `upstream.proxy_protocol`
String. The version of [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to use with this endpoint, empty if not using.
Possible values are `1` or `2`.
###### Example
```yaml {19-19} theme={null}
# ...
endpoints:
- name: example
url: https://example.ngrok.app
metadata: '{ "id": "example-app" }'
description: "our example application"
traffic_policy:
on_http_request:
- actions:
- type: custom-response
config:
status_code: 200
body: hello, Traffic Policy!
headers:
content-type: text/plain
upstream:
url: 8080
protocol: http1
proxy_protocol: 2
# ...
```
## Tunnels (deprecated)
The `tunnels` configuration field is deprecated and will be removed by the end of 2025. Please use the `endpoints` configuration field instead.
v3 still supports the `tunnels` configuration field. This is a key-value list of tunnel name to configurations.
An example can be found below:
```yaml theme={null}
# Version of the ngrok Agent Configuration file. Required.
version: 3
# Agent Configuration
agent:
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
# Tunnel Configurations
tunnels:
basic:
proto: http
addr: 80
```
### Tunnel configuration options
You can find the configuration options for `tunnels` under the [Agent Configuration v2 docs](/agent/config/v2/#tunnel-configurations).
## Example configuration files
Below are a collection of different agent configurations to serve as examples for your `ngrok.yml` file.
### Basic
Here is a basic example configuration file. In this example, authentication is done
using an authtoken and a single HTTPS endpoint named `basic` is defined with an
endpoint URL `basic.ngrok.app` and an upstream URL of `localhost:8080`.
```yaml theme={null}
# Version of the ngrok Agent Configuration file. Required.
version: 3
# Agent Configuration
agent:
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
# Endpoint Definitions
endpoints:
- name: basic
url: basic.ngrok.app
upstream:
url: 8080
```
#### Starting the `basic` endpoint
Run the following command to start the basic endpoint. Make sure you update the
authtoken in the example to your own before running the following command:
```
ngrok start basic
```
### Multiple endpoints
```yaml theme={null}
# Version of the ngrok Agent Configuration file. Required.
version: 3
# Agent Configuration. Required.
agent:
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
# Endpoint Definitions
endpoints:
- name: foo
description: foo123
metadata: foo123
url: foo.ngrok.app
upstream:
url: 8080
protocol: http1
- name: bar
url: bar.ngrok.app
upstream:
url: 8080
```
### Endpoint with inline Traffic Policy
```yaml theme={null}
# Version of the ngrok Agent Configuration file. Required.
version: 3
# Agent Configuration. Required.
agent:
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
# Endpoint Definitions
endpoints:
- name: foo
description: foo123
metadata: foo123
url: foo.ngrok.app
# Traffic Policy that will be applied to this endpoint
traffic_policy:
on_http_request:
- actions:
- type: custom-response
config:
status_code: 200
body: hello, Traffic Policy!
headers:
content-type: text/plain
upstream:
url: 8080
protocol: http1
```
### Endpoint with Traffic Policy file
```yaml theme={null}
# Version of the ngrok Agent Configuration file. Required.
version: 3
# Agent Configuration. Required.
agent:
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
# Endpoint Definitions
endpoints:
- name: bar
url: bar.ngrok.app
# Path to the Traffic Policy to be read and applied to this endpoint
traffic_policy_file: /path/to/your/traffic-policy.yml
upstream:
url: 8080
protocol: http2
```
### Endpoint with a random address
Here is an example configuration where ngrok will randomly assign your endpoint an ngrok branded address:
```yaml theme={null}
# Version of the ngrok Agent Configuration file. Required.
version: 3
# Agent Configuration. Required.
agent:
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
# Endpoint Definitions
endpoints:
# Endpoint with no endpoint URL defined to get a randomly assigned ngrok address.
- name: my_endpoint_name
#url: http:// # uncomment this line if you want your endpoint to be HTTP, by default it's HTTPS
upstream:
url: 80
```