Multiplex to Internal Services from a Single Domain

Multiplexing is a common gateway design where you host multiple services from a single fully qualified domain name (FQDN) like example.com. For example, app.example.com can serve a static web app while api.example.com serves a JSON API using entirely different services and infrastructure.

ngrok simplifies multiplexing by letting you:

1. Put a URL online to accept internet traffic to a Cloud Endpoint, which allows you to control how that traffic accesses the internal resources where your internal Agent Endpoints are running. We call this the "front door" pattern.
2. Use Traffic Policy to create dynamic routing topologies based on subdomains or headers.
3. Add new services behind your gateway without service discovery, manual registration, certificate management, split-horizon DNS zones, or any other complex networking configurations.

1. Create endpoints for your services

Start internal Agent Endpoints, replacing $PORT based on where your service listens, for each of your services on the systems where they run. You can also use one of our SDKs or the Kubernetes Operator.

Loading…

Make sure the hostname of the internal endpoint matches the subdomain or header value you want to use for routing.

• https://foo.example.com → https://foo.internal
• x-service: bar → https://bar.internal

2. Reserve a domain

Navigate to the Domains section of the ngrok dashboard and click New + to reserve a free static domain like https://your-service.ngrok.app or a custom domain you already own.

We'll refer to this domain as $NGROK_DOMAIN from here on out.

3. Create a Cloud Endpoint

Navigate to the Endpoints section of the ngrok dashboard, then click New + and Cloud Endpoint.

In the URL field, enter the domain you just reserved to finish creating your Cloud Endpoint.

4. Add multiplexing with Traffic Policy

While still viewing your new Cloud Endpoint in the dashboard, copy and paste one of the two policies below into the editor depending on whether you want to route by hostname/subdomain or header value.

Loading…

What's happening here? This policy forwards every HTTP request to one of your internal Agent Endpoints, which in turn forward traffic to your internal services. The split macro dynamically routes traffic based on the incoming hostname so that the policy forwards requests to the foo subdomain to https://foo.internal, and so on.

5. Try out your endpoint

Visit the domain you reserved either in the browser or in the terminal using a tool like curl. When you try various subdomains or header values in your requests, you should see your various APIs or apps as they're connected to your internal Agent Endpoints.

What's next?

• Add authentication like JWT validation or IP restrictions to some or all of your multiplexed services, or even combine multiple methods to let users authenticate with one OR another method.
• View your traffic in Traffic Inspector to ensure multiplexing works as expected or to find potentially abusive patterns you can block using IP Intelligence or the OWASP action.

← Back to other examples

Want to contribute to the examples gallery?