Skip to main content

Internal Endpoints

Internal Endpoints are private endpoints that only receive traffic when forwarded through the forward-internal traffic policy action. This allows you to route traffic to an application through ngrok without making it publicly addressable.

Internal endpoint URLs must:

  • End with the .internal domain extension
  • Use the internal binding

A common practice is to use a public cloud endpoints to manage a centralized Traffic Policy, then forward traffic to one or more internal endpoints. See the guide on using cloud endpoints with internal endpoints to learn more.

Quickstart​

Agent Endpoint​

Create an internal agent endpoint by specifying a binding of internal when you create an endpoint.

Loading…

Cloud Endpoint​

Instead of an agent endpoint, you can create an internal cloud endpoint.

Specify a binding of internal when you create the cloud endpoint.

Loading…
traffic-policy.yml​
Loading…

Forwarding​

Internal endpoints aren’t directly accessible. To send traffic to an Internal Endpoint, you must create an endpoint that uses the Traffic Policy to forward traffic using the forward-internal action.

For example, to route public traffic to your internal endpoint, use the following command and traffic policy to create a Public Cloud Endpoint that forwards requests to your Internal Endpoint:

Loading…
traffic-policy.yml​
Loading…

Now, when you make a request to https://your-name.ngrok.app, ngrok applies the specified traffic policy. This policy instructs ngrok to use the forward-internal action, routing the incoming HTTP request directly to your internal endpoint at https://example.internal.

This configuration lets you manage how traffic reaches your service without requiring it to be directly accessible on the public internet.

Inferred Binding​

ngrok automatically infers an internal binding for any endpoint created with a .internal hostname, so you can omit the binding property in most cases.

For example, the following command creates an endpoint with an internal binding:

Loading…

URLs​

  • Scheme - Internal endpoints support all Endpoint Protocols (http, https, tcp and tls).
  • Hostname - Hostnames must end with .internal and may contain up to 5 subdomains. You must specify a URL with a hostname, randomly-assigned hostnames are not supported. You may specify wildcard hostnames.
  • Port - All port numbers [1-65535] are valid. For tcp endpoints, you must specify a port.
  • Namespacing - Internal endpoints are namespaced on a per-account basis. This means that, two different accounts may have internal endpoints with the same URL (e.g. https://api.internal) without conflict or interference in endpoint pooling.

Examples​

  • https://example.internal
  • https://example.foo.bar.internal
  • https://example.internal:12345
  • tls://example.internal
  • tls://example.internal:12345
  • tcp://example.internal:12345

Type and Pooling​

HTTP/S on_tcp_connect phase​

For internal http and https endpoints, the on_tcp_connect Traffic Policy phase is not applicable and never triggers.

This is because when you use the forward-internal action to forward traffic to an http or https endpoint, no new TCP connection is established. For additional details, see the forward-internal documentation.

API​

Internal endpoints can be managed programatically. To get started, consult the Endpoints API documentation.

Pricing​

Internal endpoints are available on the Pay-as-you-go plan. Consult the Endpoints Pricing documentation for billing details.