Configuration precedence when ngrok YAML and CLI define the same tunnel

Question

The goal is to define multiple tunnels with custom domains for local services using ngrok's configuration mechanisms. The agent is documented to support both a YAML configuration file and command-line arguments for tunnel definitions, and it establishes a secure connection to the ngrok cloud edge to route ingress traffic to the local port.

There is uncertainty about how the agent resolves overlapping definitions when the same tunnel name, port, or domain is specified in both the YAML file and the CLI invocation. The interaction between file-based configuration and CLI overrides is a design decision that may vary with agent version, and the documented merge behavior is not clearly established for all protocol types including HTTP, HTTPS and raw TCP.

Which configuration source takes precedence for a tunnel when both YAML and CLI specify the same name? Does the agent merge settings from both sources or does one source fully override the other? When duplicate definitions are present, is the result deterministic across agent versions?

Wasi · Answer

Direct answer
For a duplicate tunnel name, the CLI definition takes precedence for that invocation, but ngrok generally replaces the whole tunnel rather than merging individual fields from YAML and CLI. The config-file tunnel is suppressed for that run, and settings such as custom domain, address, or protocol options defined only in YAML can be lost. Whether this appears as a silent override or a startup error depends on the ngrok major version and invocation mode.
Confirmed facts versus likely behavior
Confirmed: CLI flags override config-file values for global agent settings, including authtoken, region, log level, and config path. The YAML file supplies defaults.
Not confirmed from primary documentation: exact named-tunnel merge behavior for HTTP, HTTPS, and raw TCP. Model knowledge indicates whole-tunnel override rather than per-field merging, and behavior differs between ngrok v2 and v3 and between ngrok start and ad-hoc commands such as ngrok http.
Steps for this case

Run ngrok version to confirm v2 or v3 semantics.
Use ngrok config check, if available, to verify which config file is loaded and which tunnels are listed.
Avoid reusing the same tunnel name on the CLI when you want the YAML custom domain to apply; use a distinct name or omit the CLI tunnel definition.
Start with increased logging and compare the startup-reported tunnel name, address, and domain against your YAML and CLI inputs.

Missing diagnostic detail
Provide your ngrok version and exact command, for example ngrok start --all versus ngrok http 8000. This changes the recommendation because duplicate-name handling is not consistent across versions or invocation modes.
Assumptions and uncertainty

This answer assumes a named-tunnel conflict, not a conflict between global options only.
Results are deterministic within a fixed major version and invocation mode, but not across v2 versus v3 or start versus ad-hoc modes.
Raw TCP tunnel behavior is less documented than HTTP/HTTPS and should be verified separately.

Configuration precedence when ngrok YAML and CLI define the same tunnel

1 answer

Direct answer

Confirmed facts versus likely behavior

Steps for this case

Missing diagnostic detail

Assumptions and uncertainty

Your perspective belongs here.

0 question comments