HTTP/S Endpoints - ngrok documentation

HTTP/S endpoints enable you to serve web services like REST APIs, web applications, websites and websocket servers. Serving a web application is as simple as ngrok http 80. Once your endpoint is running, check out:

Traffic Policy - Add routing, authentication and traffic transformation
Traffic Inspector - Real-time observability with request/response introspection
Endpoint Pooling - Load balancing

Quickstart

Agent Endpoint

Agent Endpoints are the easiest way to get started with ngrok. An agent endpoint is started by a Secure Tunnels agent. The endpoint lives for the lifetime of the process and forwards traffic to a port or URL of your choosing. Create the endpoint https://example.ngrok.app and forward its traffic to a local port.

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http 8080 --url https://example.ngrok.app

Cloud Endpoint

Cloud endpoints are created via the ngrok Dashboard or API. They are persistent and live until they are deleted. Traffic Policy controls how a cloud endpoint handles traffic. Create an HTTPS cloud endpoint which returns a Hello world! 200 OK response.

Agent CLI

Command line

ngrok api endpoints create \
  --url https://example.ngrok.app \
  --traffic-policy "$(<traffic-policy.yml)"

traffic-policy.yml

on_http_request:
  - actions:
      - type: custom-response
        config:
          status_code: 200
          headers:
            content-type: text/plain
          body: "Hello world!"

URL

URLs are validated differently depending on their binding. Consult the following documentation for details on valid URLs for TCP endpoints:

Public

HTTP

The hostname must be a domain with a valid public suffix.
The port must be 80. If you do not specify a port, the default 80 will be used for you.

Examples

http://example.ngrok.app
http://example.ngrok.app:80
http://example.party
http://example.ngrok.app:81 - invalid port: port number must be 80, not 81
http://example.doesnotexist - invalid hostname: .doesnotexist is not a public suffix domain
http://example.internal - invalid hostname: .internal is not a public suffix domain

HTTPS

The hostname must be a domain with a valid public suffix.
The port must be 443. If you do not specify a port, the default 443 will be used for you.

Internal

Kubernetes

Valid URLs

Invalid URLs

Validation

When you create an agent endpoint, if you do not specify a complete URL, following defaults are used to construct an endpoint URL. When you create a cloud endpoint, you must always specify both a scheme and hostname.

URL Part	Default
Scheme	`https`
Hostname	randomly selected
Port	`443` if scheme is `https` `80` if scheme is `http`

Consult the following table of examples of URL defaulting:

Value	Endpoint URL
`https://example.ngrok.app`	`https://example.ngrok.app`
`http://example.ngrok.app`	`http://example.ngrok.app`
`example.ngrok.app`	`https://example.ngrok.app`
`app.example.com`	`https://app.example.com`
`https://example.internal`	`https://example.internal`
`https://example.internal:1234`	`https://example.internal:1234`
`http://example.internal`	`http://example.internal`
`foo.internal`	`https://foo.internal`
`{empty}`	`https://1eb2-181-80-12-3.ngrok.app` (randomly selected)

If you would like to listen for both http and https traffic, create two endpoints.

Domains

When you create a public endpoint, it must match a Domain on your account. Domains help you set up branded domains and manage TLS certificates. You may create endpoints with wildcard domains as well. Endpoints with randomly-assigned hostnames are an exception and won’t match an existing Domain object.

Bring your own domain

If you want to bring your own domain, first create a Domain record and set up a DNS CNAME record. Then create an endpoint on that domain by specifying a URL with a matching hostname. For example, to create an HTTPS endpoint on https://app.example.com, create a Domain and follow the instructions to set up a CNAME record. Then use the following example to start an endpoint on your domain:

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http 80 --url https://app.example.com

Wildcard endpoints

You can create an endpoint which will receive traffic for all of the subdomains matching a given wildcard domain like *.example.com. You must create a wildcard domain to create a public wildcard endpoint. For example, if you create the wildcard endpoint https://*.example.com, it will receive traffic for https://foo.example.com and https://bar.example.com.

Connections to URLs which match an online wildcard endpoint will be routed to it. For example, if you have created a wildcard endpoint https://*.example.com, connections to https://foo.bar.baz.example.com will route to it.
Connections are routed to the most specific online endpoint. For example, if the endpoints https://*.example.com and https://app.example.com are both online, a connection to https://app.example.com will not be routed to the wildcard endpoint.

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http 80 --url "https://*.example.com"

Use multiple endpoints with wildcard subdomains

With the Agent CLI, you can create separate public endpoints for subdomains of a wildcard domain no matter where the upstream services are running. See the Domains docs for more information. For example, if you reserve *.example.com and want to route requests to api1.example.com and api2.example.com, you can specify subdomains via the CLI. ngrok will handle routing requests to the correct endpoint, even if they’re on different ports. The first one might be at port 80:

ngrok http 80 --url https://api1.example.com

While the second is at port 81:

ngrok http 81 --url https://api2.example.com

This is only necessary for creating public endpoints to subdomains. Internal endpoints don’t require a domain.

Randomly assigned hostnames

If you run create a public endpoint without specifying a hostname, ngrok will automatically assign a random one for you.by selecting a random subdomain of one of our ngrok-managed Domains to your endpoint. For example, the command ngrok http 80 may create an endpoint like https://1eb2-181-80-12-3.ngrok.app. The following example create an HTTPS endpoint on a randomly assigned hostname that forwards to port 8080.

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http 8080

Traffic Policy

Attach Traffic Policy to endpoints to route, authenticate and transform the traffic through the endpoint.

Authentication

Public endpoints are accessible to the public internet unless you secure them with authentication. That’s desirable if you’re hosting a public website but most often you want to add authentication. You can secure your endpoints with Traffic Policy with any of the following actions:

Basic Auth Example

Adds a username and password with the Basic Auth Traffic Policy action.

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http 80 --traffic-policy-file traffic-policy.yml

`traffic-policy.yml`

on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - username1:password1
            - username2:password2

Google OAuth Example

The following example enforces a browser-based OAuth redirect flow in front of your endpoint using Google as the identity provider by using the OAuth Traffic Policy action.

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http 80 --traffic-policy-file traffic-policy.yml

`traffic-policy.yml`

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google

Rewriting the `host` header

Some application servers expect the host header to match a specific value when they receive requests and some use the host header to determine which of many sites to display. ngrok can rewrite the host header of incoming requests so that your application behaves correctly. When you rewrite the host header, ngrok also rewrites the location header of HTTP responses automatically to match the hostname of your Endpoint URL. The following example rewrites the host header to the value localhost using the add-headers Traffic Policy action. Adding the Host header is a special case that replaces the existing Host header instead of appending a second value.

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http 8080 --traffic-policy-file traffic-policy.yml

`traffic-policy.yml`

on_http_request:
  - actions:
      - type: add-headers
        config:
          headers:
            host: localhost

Agent Forwarding

The ngrok agent and Agent SDKs forward traffic that your endpoints receive to upstream services. You specify a URL or port number to instruct the ngrok agent where and how to forward traffic.

HTTPS forwarding

The scheme in your upstream URL is used to determine whether to forward HTTP or HTTPS traffic to the upstream service. If you do not specify a scheme, the default http scheme is chosen unless you forward to port 443, in which case ngrok will use https. Consult the following table of examples.

Upstream URL	Normalized Value
`http://localhost:1234`	`http://localhost:1234`
`https://localhost:1234`	`https://localhost:1234`
`localhost:1234`	`http://localhost:1234`
`1234`	`http://localhost:1234`
`localhost:443`	`https://localhost:443`
`443`	`https://localhost:443`

ngrok assumes that the network you run the agent on is private and it does not verify the TLS certificate presented by the upstream service. You may change this behavior with the flags --upstream-tls-verify and upstream-tls-verify-cas.

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http https://localhost:8443

Non-local forwarding

Agents don’t just forward to ports on your localhost. You can forward traffic to any address or URL reachable from the agent. For example, if you want to forward traffic to a HTTP server running on your network at 192.168.1.2:80:

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http 192.168.1.2:80

HTTP/2 forwarding

When agents forward to upstream http/2 services, connections use HTTP/1.1 by default. You can configure the agent, SDKs and Kubernetes Operator to instead use HTTP/2 when forwarding to your upstream service.

Forwarder	Option	Docs
Agent	`--upstream-protocol`	Agent CLI flags
Agent SDKs	language-dependent	Agent SDKs
Kubernetes Operator	`appProtocol` on the `Tunnel` CRD	Kubernetes Operator

When http2 forwarding is enabled, all requests to your upstream service will be transmitted over HTTP/2 Cleartext since TLS was already terminated at the ngrok cloud service. We cannot use TLS-ALPN at this time. We rely on HTTP/2 with Prior Knowledge currently.

Serving file directories

The ngrok agent supports the file:// scheme in a forwarding URL. When you use the file:// scheme, the ngrok agent serves local file system directories by using its own built-in file server, no separate server needed. It works just like python3 -m http.server but it is built directly into the ngrok agent. Paths in file:// URLs must be specified as absolute paths.

Serve files in `/var/log`

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http "file:///var/log"

Serve files on Windows

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http "file://C:\Users\alan\Directory Name"

Serve files in your current working directory

Agent CLI
Agent Config
SSH Reverse Tunnel
Go
Javascript
Python
Rust
Kubernetes Controller

ngrok http file://`pwd`

Traffic Observability

Traffic Inspector

Traffic Inspector gives you a real-time view in the ngrok dashboard of the HTTP traffic flowing through your HTTP/S endpoints. You can choose whether Traffic Inspector captures only request metadata or full request and response bodies.

Log Export Logs

You can export logs of traffic to HTTP/S endpoints with ngrok’s events system. The following events are published for log exporting:

Log	When
http_request_complete.v0	Published when an HTTP request to an HTTP/S endpoints completes.
tcp_connection_closed.v0	Published when a TCP connection to an HTTP/S endpoints completes.

Advanced

HTTP/S endpoints are standards-compliant HTTP reverse proxies.

Versions

HTTP/S endpoints support HTTP/1.1.
HTTPS endpoints support HTTP/1.1 and HTTP/2.
HTTP/1.0, HTTP/3 and QUIC are not supported.

HTTP/2

HTTPS endpoints will automatically use HTTP/2 for all connections if the client supports it. Client support is determined via standard ALPN negotiation. HTTP/2 is used between the client and your endpoint even even if your upstream service does not support HTTP/2. The section on HTTP/2 agent forwarding has details on how to configure the use of HTTP/2 when sending traffic to an upstream service.

Websockets

Websocket connections are supported out-of-the-box. No configuration is required.

Hop by hop headers

ngrok does not forward any hop-by-hop headers to the upstream service. As an exception, Connection: upgrade headers are forwarded to support websockets. For information on headers added automatically by ngrok, see Upstream Headers.

Persistent connections

When a connection is made to HTTP/S ngrok endpoints with HTTP/1.1, ngrok may choose to use persistent connections (aka HTTP keep-alive) to improve the performance of future requests from the same client if the client supports it. This behavior is not guaranteed and it is not configurable. See RFC 7230 for additional details.

Well Known URIs

`/.well-known/acme-challenge`

ngrok takes over handling of this path of any HTTP endpoint matching a Domain with automated certificate management enabled. You may disable this behavior by uploading your own certificate on the matching Domain.

TLS

ngrok automatically handles TLS (SSL) certificate management and termination for you. There is nothing to setup, configure or manage. TLS connections to https endpoints are terminated at ngrok’s cloud service. If you wish to terminate TLS traffic at the ngrok agent or in your upstream application, use a TLS Endpoint instead. Consult the following documentation for additional details on how ngrok handles TLS termination and certificiate management:

Upstream Headers

ngrok adds headers to each HTTP request with information about the original client IP, request scheme and request host header value.

Header	Description
`x-forwarded-for`	The IP address of the client who initiated the request. If this header exists on the original request, ngrok will append a new value.
`x-forwarded-proto`	The scheme of the original request, either `http` or `https`. If this header exists on the original request, ngrok will append a new value.
`x-forwarded-host`	The header from the client’s request if it existed, otherwise is set to the request’s `Host` header value.

Because ngrok appends values to x-forwarded-for and x-forwarded-proto, be sure to use the last value of the header in your application code to read the values injected by ngrok. You may remove these headers with the Remove Headers Traffic Policy action.

Limits & Timeouts

Connection

Limit	Name	Notes
5 minutes	Client Idle Timeout	Time since data was last transmitted by the upstream service
5 minutes	Server Idle Timeout	Time since data was last transmitted by the upstream service
No limit	Data transmitted	Data transmitted by the client or upstream service

TLS

Limit	Name	Notes
60 seconds	TLS Handshake Duration	Time between ClientHello received and handshake completion
64 KB	Handshake Message Size	Max size of non-certificate handshake messages
256 KB	Certificate Message Size	Max size of certificate handshake messages
16 KB	Record Payload Size

HTTP

Limit	Name	Notes
No timeout	Round Trip Timeout	Time for the entire HTTP request and response

HTTP Request

Limit	Name	Notes
1 MB	Request Header Size	Includes method, URI and headers
1 MB	Request URI Length	Limited by the size of the request header
No timeout	Request Timeout	Time to read the entire HTTP request from the client
No timeout	Request Header Timeout	Time to read the HTTP request header from the client
No limit	Request Body Size

HTTP Response

Limit	Name	Notes
1 MB	Response Header Size	Includes method, URI and headers
No timeout	Response Timeout	Time to read the entire HTTP response from the server
No timeout	Response Header Timeout	Time to read the HTTP response header from the server
No limit	Response Body Size

Errors

If ngrok fails to handle an HTTP request it will set the ngrok-error-code header in the HTTP response with a unique ngrok Error Code describing the failure. ngrok guarantees that the upstream service may never set the ngrok-error-code HTTP response header so you know reliably that it was set by ngrok. ngrok may return an error under the following conditions:

Your upstream service timed out or rejected the connection
Your upstream service returned a response that was not valid HTTP
A Traffic Policy action rejected the request.
Traffic Policy execution encountered a runtime error.
ngrok encountered an internal error

API

HTTP/S Endpoints can be created programmatically. Consult the documentation on Endpoint APIs.

Pricing

HTTP/S endpoints are available on all plans. Consult the Endpoints Pricing documentation for billing details. See Domains pricing for details on pricing for custom domains, wildcard domains and more.

Concepts

Endpoints

Network

Examples

​Quickstart

​Agent Endpoint

​Cloud Endpoint

​URL

​Public

HTTP

HTTPS

​Internal

​Kubernetes

Valid URLs

Invalid URLs

​Validation

​Domains

​Bring your own domain

​Wildcard endpoints

​Use multiple endpoints with wildcard subdomains

​Randomly assigned hostnames

​Traffic Policy

​Authentication

​Basic Auth Example

traffic-policy.yml

​Google OAuth Example

traffic-policy.yml

​Rewriting the host header

traffic-policy.yml

​Agent Forwarding

​HTTPS forwarding

​Non-local forwarding

​HTTP/2 forwarding

​Serving file directories

​Serve files in /var/log

​Serve files on Windows

​Serve files in your current working directory

​Traffic Observability

​Traffic Inspector

​Log Export Logs

​Advanced

​Versions

​HTTP/2

​Websockets

​Hop by hop headers

​Persistent connections

​Well Known URIs

​/.well-known/acme-challenge

​TLS

​Upstream Headers

​Limits & Timeouts

​Connection

​TLS

​HTTP

​HTTP Request

​HTTP Response

​Errors

​API

​Pricing

Quickstart

Agent Endpoint

Cloud Endpoint

URL

Public

Internal

Kubernetes

Validation

Domains

Bring your own domain

Wildcard endpoints

Use multiple endpoints with wildcard subdomains

Randomly assigned hostnames

Traffic Policy

Authentication

Basic Auth Example

`traffic-policy.yml`

Google OAuth Example

`traffic-policy.yml`

Rewriting the `host` header

`traffic-policy.yml`

Agent Forwarding

HTTPS forwarding

Non-local forwarding

HTTP/2 forwarding

Serving file directories

Serve files in `/var/log`

Serve files on Windows

Serve files in your current working directory

Traffic Observability

Traffic Inspector

Log Export Logs

Advanced

Versions

HTTP/2

Websockets

Hop by hop headers

Persistent connections

Well Known URIs

`/.well-known/acme-challenge`

TLS

Upstream Headers

Limits & Timeouts

Connection

TLS

HTTP

HTTP Request

HTTP Response

Errors

API

Pricing