Skip to main content

Connect URL

Overview​

The Connect URL is the hostname and port the ngrok agent (and agent SDKs) use to establish its control connection to the ngrok service. By default, agents use connect.ngrok-agent.com:443. You can change this per agent by setting the connect_url field in your configuration file.

Custom Connect URL​

Create a custom Connect URL to customize how your agents connect (for example connect.example.com:443). This involves delegating a DNS subdomain and configuring certificates for the new address.

Key points:

  • Agents connecting via your custom Connect URL must authenticate to your ngrok account; connections using credentials from other accounts are rejected.
  • Custom Connect URLs support both ngrok‑issued and Let’s Encrypt certificates.

Create a custom Connect URL​

  1. Choose a domain you own
  • You will delegate a subdomain via NS records to ngrok so we can manage the required DNS (A/AAAA) and certificates.
  1. Create the Connect URL entry
  1. Pick a certificate issuer
  • ngrok Internal CA (fast, private CA, may require trust in some networks)
  • Let’s Encrypt (public CA, may require additional provisioning time)

Delegate DNS records​

After creation, the Dashboard prompts you to add NS records for the selected subdomain at your DNS provider.

Update agent configuration​

Point your agents at the new address by setting connect_url. The helper command ngrok config add-connect-url can update your config for you.

For example, if the domain of your custom Connect URL is connect.example.com then you might add the following line to the agent's configuration file:

Loading…

Regional scope and GSLB​

Custom Connect URLs are pinned to a specific region for the agent’s control connection and do not use Global Server Load Balancing for that connection. End-user traffic to your endpoints is still delivered using GSLB.

Dedicated IPs​

When you create a custom Connect URL, DNS and certificates are branded to your domain, but the address still resolves to ngrok’s shared IPs. If you need static, account‑unique addresses, Dedicated IPs are available. Contact us for details.

Certificate Issuer​

When you create a custom Connect URL, choose one of two certificate issuers:

ngrok Internal CA​

  • Default option; provisioned immediately.
  • Trusted by the ngrok agent out of the box.
  • Some enterprise inspection tools may not trust this private CA without additional configuration.

Let’s Encrypt​

  • Public CA; useful when corporate proxies or network devices cannot trust a private CA.
  • May require setting root_cas: host (or providing the Let’s Encrypt root) for some SDKs and for the SSH Reverse Tunnel agent.
  • Provisioning can take time (DNS propagation). ngrok issues a temporary certificate until Let’s Encrypt is ready. Even if DNS checks pass in the Dashboard, Let’s Encrypt may still be propagating.

If you select Let’s Encrypt, the Connect URL drawer shows a status card while the certificate is provisioning:

note

Certificates issued by Let’s Encrypt through ngrok are securely managed. Private keys are not exposed to requesters.

Why customize the Connect URL?​

Branded Connectivity​

If you use ngrok for production connectivity (devices in the field or customer environments), a custom Connect URL lets you brand connectivity with your domain.

Policy Enforcement​

For development and testing, a custom Connect URL helps enforce policy:

  • Ensure developers use a shared ngrok account (not personal accounts).
  • Block default Connect URLs on corp networks while allowing your custom URL.

Pricing​

Custom Connect URLs are not available on self‑serve plans. Contact us to discuss options.