Skip to main content

TLS Termination


This module enables you to configure TLS termination at either your upstream service, the ngrok edge or the ngrok agent. It also allows you to configure the parameters of that termination.

By default, TLS endpoints terminate TLS connections at your upstream service. This means that by default, ngrok does not terminate TLS connections, your upstream service must handle TLS termination.

Terminating TLS at the ngrok edge is a good choice in the following circumstances:

  • You want ngrok to automatically manage TLS certificate provisioning for you.
  • You want ngrok to enforce Mutual TLS. TLS Termination is required to enforce mTLS.
  • You want to accelerate TLS termination by executing it at ngrok's edge, closer to your clients
  • Your upstream service can't terminate TLS. This is common for legacy software.

Example Usage

Terminate at upstream service

ngrok tls 443 \
--terminate-at upstream \

Terminate at ngrok edge

ngrok tls 80 --terminate-at edge

Terminate at ngrok agent

ngrok tls 80 \
--terminate-at agent \
--domain \
--crt /path/to/app-example-com-crt.pem \
--key /path/to/app-example-com-key.pem

Custom cert at ngrok edge

ngrok tls 80
--domain \
--terminate-at edge \
--crt /path/to/app-example-com-crt.pem \
--key /path/to/app-example-com-key.pem



The following section will help you resolve any certificate errors you run into while using TLS termination. Because TLS endpoints are flexible enough to terminate TLS at either the ngrok edge, the ngrok agent or your upstream service, you may encounter certificate errors. Understanding how the ngrok platform handles certificates can help resolve them quickly.

When you terminate TLS at the ngrok edge, you may choose between bringing your own certificates and allowing ngrok to automatically provision certificates for you from an ACME provider like Let's Encrypt. If you use automatic certificates, ngrok will choose a matching, valid certificate for you and it will provision and renew that, if necessary. This works even if you're listening on a randomly-chosen ngrok domain.

When using Zero-Knowledge TLS by terminating at the ngrok agent or at your upstream service, you should always specify a domain. If you don't specify a domain to listen on, you won't have already provisioned a signed certificate for that domain. Make sure that the certificate you're using exactly matches the name of the domain you've asked ngrok to listen on.

Zero-Knowledge TLS

When TLS is not terminated at the ngrok edge, then your TLS connections are end-to-end encrypted (E2EE) which we call Zero-Knowledge TLS. When your TLS endpoints operate in this mode, the ngrok edge can not see the payloads that transfer through your endpoints.

The ngrok edge enables Zero-Knowledge TLS by using the SNI data of incoming TLS connections to route them to the proper endpoint without terminating TLS. The unterminated connections are forwarded all the way through to your upstream application which is then responsible for TLS termination.

Zero-Knowledge TLS at the Agent

If the service you are exposing does not support TLS termination, you can still take advantage of Zero-Knowledge TLS. The ngrok agent can terminate TLS for you allowing you to encrypt your traffic end-to-end without reconfiguring your upstream service. This is often a good choice if your upstream service is a piece of legacy software that doesn't support TLS or if it's operated out of your control.

Specify --terminate-at agent with both the --crt and --key command-line options when starting the agent to specify the filesystem paths to your TLS certificate and key and the ngrok agent will take care of terminating TLS connections for you.

TLS Version Choice

If you configure ngrok to do TLS termination, either at the edge or in the agent, it will prefer to use TLS 1.3 if the client supports it.

When terminating at the ngrok edge, a minimum supported version of TLS 1.2 is chosen by default. Clients that do not support TLS 1.2 will not be able to connect. This value is configurable when using Edges.

When terminating at the ngrok agent, a minimum supported version of TLS 1.2 is chosen by default. Clients that do not support TLS 1.2 will not be able to connect. This value is not configurable.



Terminate AtupstreamWhere to terminate TLS. One of: edge, upstream, agent
Minimum TLS Version1.2The minimum version of TLS to negotiate. Clients which do not support at least this version of TLS will be unable to connect.


This module does not return any errors.


No event data is captured for this module on TLS endpoints.


TLS Termination is a supported TLS Edge module.


This module is available on the Enterprise plan.

Try it out

Coming Soon

This documentation is incomplete. Please check back later, we appreciate your patience.