Ngrok Path-Based Ingress: Route Local Services Through a Single HTTPS Tunnel

Desired outcome

You need to make one or more local development services reachable over the internet without provisioning separate domains, DNS records, and TLS certificates for each. Ngrok’s path-based ingress routing solves this by letting you declare path patterns that map to specific local endpoints, all funneled through a single public HTTPS URL. Traffic arrives at the ngrok edge, where TLS is terminated and certificates are generated automatically, so your local services never need to speak TLS.

Necessary prerequisites

Before you begin, ensure you have:

• A ngrok account with an authtoken installed on your machine (ngrok config add-authtoken <YOUR_TOKEN>).
• A local service running on a known port (e.g., localhost:8080 or localhost:3000).
• Ngrok commercial edition for full path‑based rule syntax; open‑source editions support basic path prefixes but may differ in priority handling.

Install ngrok and authenticate

ngrok config add-authtoken <YOUR_NGROK_AUTH_TOKEN>

Run this once per machine. The token is stored in ~/.ngrok2/ngrok.yml and persists across sessions.

Rule priority and edition differences

The following table illustrates how path‑based rule priority varies between ngrok editions:

Edition	Rule order effect	Path pattern support
Commercial	First declared rule matches first; deterministic sharding.	Exact prefix, host‑constrained patterns available.
Open source	May evaluate rules in declaration order, but syntax restrictions apply.	Often limited to a single path prefix per tunnel.

Focused procedure

1. Create a ngrok configuration file (e.g., ngrok.yml) that defines your ingress rules. Commercial editions support the ingress section; open‑source may use command‑line flags.

ingress:
  - path: /api
    addr: localhost:8080
  - path: /web
    addr: localhost:3000

In this example, requests whose path starts with /api are forwarded to the service on port 8080, and paths starting with /web go to port 3000. Rule order matters: the first matching rule wins, enabling deterministic sharding without an external load balancer.

Start ngrok with the configured tunnel

ngrok start --config ngrok.yml http 8080

Alternatively, you can inline rules via environment variables, but a YAML config is the supported path for multi‑rule setups.

Expected checks

After ngrok initializes, verify the routing works as intended:

1. Send a request to the path‑specific public URL: curl -k https://<subdomain>.ngrok.io/api. The response should originate from your local service on port 8080.
2. Repeat with the other path: curl -k https://<subdomain>.ngrok.io/web and confirm the response comes from port 3000.
3. Check that the TLS certificate is valid and issued by ngrok’s edge; you can view it via your browser’s security details.

If either request returns a connection error or a response from the wrong service, re‑examine the rule order and addr values in your config.

Known limitations and version constraints

Ngrok’s path‑based ingress feature behaves differently between the open‑source and commercial editions. In commercial editions, rule priority follows strict declaration order, and path patterns support exact prefix matching with optional host constraints. Open‑source releases may restrict rules to a single path prefix or require additional flags, and rule order may not guarantee the same deterministic sharding. Additionally, custom domain TLS provisioning requires you to prove DNS ownership via a CNAME record; failed validation will prevent the tunnel from initializing, and the tunnel will default to a random ngrok subdomain.

Rate limiting and per‑rule metrics are exposed through ngrok’s diagnostic endpoints, but they apply per‑ingress rule and do not isolate traffic between rules; a high‑volume request to one path can still impact overall tunnel capacity.

Recovery and rollback

Modifying the ingress rules changes the routing state of your active tunnel. To recover a previous configuration, simply replace the ngrok.yml file with the earlier version and restart ngrok: ngrok kill followed by ngrok start --config ngrok.yml. Because ngrok tunnels are ephemeral, there is no persistent state to lose; a restart with the prior config restores the expected mapping.