SOP 006: Configure Custom Domain

Fresh

Field	Value
SOP ID	SOP-006
Version	1.0
Status	Active
Last Updated	2026-02-13

Purpose

Configure a custom domain or subdomain for your ngrok endpoint instead of using the randomly assigned URL.

Prerequisites

• ngrok installed and authenticated
• A paid ngrok plan (custom domains require paid plans)
• Access to your domain's DNS settings (for custom domains)

Procedure

Option A: ngrok Subdomain

1. Reserve a domain at dashboard.ngrok.com/domains
2. Use the --url flag:

ngrok http 8080 --url https://myapp.ngrok.app

Or in your config file:

endpoints:
  - name: myapp
    url: https://myapp.ngrok.app
    upstream:
      url: 8080
      protocol: http1

Option B: Custom Domain (e.g., tunnel.example.com)

1. Reserve the domain in the ngrok dashboard
2. Add a CNAME DNS record pointing to your ngrok domain:
   • Name: tunnel (or your chosen subdomain)
   • Value: The CNAME target shown in the ngrok dashboard
3. Wait for DNS propagation (can take up to 48 hours, usually minutes)
4. Start your endpoint:

ngrok http 8080 --url https://tunnel.example.com

Free Dev Domain

All accounts get a free dev domain that is automatically assigned when you start an endpoint without --url. This domain changes each session on free plans.

Managing Domains via API

ngrok api reserved-domains list

Verification Checklist

• [ ] Domain reserved in ngrok dashboard
• [ ] DNS CNAME record configured (for custom domains)
• [ ] ngrok http PORT --url DOMAIN starts without errors
• [ ] Domain resolves correctly in browser
• [ ] TLS certificate is valid (auto-managed by ngrok)

Troubleshooting

Issue	Solution
Domain not found	Ensure domain is reserved in the dashboard
DNS not resolving	Check CNAME record and wait for propagation
TLS certificate error	ngrok auto-manages certs; allow a few minutes
ERR_NGROK_DOMAIN	Domain may be in use by another account

See Also

• SOP 003: Expose Local Service
• SOP 004: Configure Traffic Policy