HTTP/S Endpoints
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
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Loading…
Loading…
Javascript SDK Docs:
Loading…
Python SDK Docs:
Loading…
Rust Crate Docs:
Loading…
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
Loading…
Loading…
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 default80
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 be80
, not81
http://example.doesnotexist
- invalid hostname:.doesnotexist
is not a public suffix domainhttp://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 default443
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
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Loading…
Loading…
Javascript SDK Docs:
Loading…
Python SDK Docs:
Loading…
Rust Crate Docs:
Loading…
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 tohttps://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
andhttps://app.example.com
are both online, a connection tohttps://app.example.com
will not be routed to the wildcard endpoint.
- Agent CLI
- Agent Config
- SSH
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Loading…
Loading…
Javascript SDK Docs:
Loading…
Python SDK Docs:
Loading…
Rust Crate Docs:
Loading…
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
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Loading…
Loading…
Javascript SDK Docs:
Loading…
Python SDK Docs:
Loading…
Rust Crate Docs:
Loading…
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
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Loading…
Javascript SDK Docs:
Loading…
Python SDK Docs:
Loading…
Rust Crate Docs:
Loading…
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
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Loading…
Javascript SDK Docs:
Loading…
Python SDK Docs:
Loading…
Rust Crate Docs:
Loading…
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
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Loading…
Javascript SDK Docs:
Loading…
Python SDK Docs:
Loading…
Rust Crate Docs:
Loading…
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
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Forwarding to an upstream HTTPS service is not supported via SSH.
Loading…
For HTTP/2 Use: config.HTTPEndpoint(config.WithAppProtocol("http2"))
Go Package Docs:
Loading…
Javascript SDK Docs:
Loading…
Python SDK Docs:
Loading…
Rust Crate Docs:
Add the k8s.ngrok.com/app-protocols
label to the Service definition
targeted by your ingress backend to instruct the Operator to use
https
when forwarding connections.
Loading…
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
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Loading…
Loading…
Javascript SDK Docs:
Loading…
Python SDK Docs:
Loading…
Rust Crate Docs:
The ngrok Kubernetes Operator always forwards its traffic. All of our other
examples show the most common forwarding case: a Service
object that defines
a label selector of matching pods to forward traffic to.
But you can also forward to an explicit set of IP
addresses
on the same network using Service
and EndpointSlice
objects.
Loading…
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
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Serving directory files is not supported via SSH.
Loading…
Serving directory files is not supported in the Javascript SDK.
Serving directory files is not supported in the Python SDK.
Serving directory files is not supported in the Rust SDK.
Serving directory files is not supported in the ngrok Kubernetes Operator.
Serve files on Windows
- Agent CLI
- Agent Config
- SSH
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Loading…
Serving directory files is not supported via SSH.
Loading…
Serving directory files is not supported in the Javascript SDK.
Serving directory files is not supported in the Python SDK.
Serving directory files is not supported in the Rust SDK.
Serving directory files is not supported in the ngrok Kubernetes Operator.
Serve files in your current working directory
- Agent CLI
- Agent Config
- SSH
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
Loading…
Serving the current working directory is not supported via the agent configuration file.
Serving directory files is not supported via SSH.
Loading …
Serving directory files is not supported in the Javascript SDK.
Serving directory files is not supported in the Python SDK.
Serving directory files is not supported in the Rust SDK.
Serving directory files is not supported in the ngrok Kubernetes Operator.
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 Events
You can export logs of traffic to HTTP/S endpoints with ngrok's events system. The following events are published for log exporting:
Event | 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
Contact us if you need to configure limits and timeouts on connections to HTTP endpoints.
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 programatically. 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.