DocsGuidesCustom subdomains

Custom subdomains

By default the edge hands you a random, memorable name. If you want something stable — for OAuth callback URLs, for a demo link you share more than once — you can ask for it explicitly.

Random vs chosen names#

Without a --subdomain flag, the server assigns a random name like amber-fox-42:

$ ngstone port 3000
→ https://amber-fox-42.ngstone.site

Pass --subdomain (or its shorthand -s) to request a specific one instead:

$ ngstone port 3000 --subdomain demo
→ https://demo.ngstone.site

Naming rules#

Chosen names are validated against a single pattern:

^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Lowercase letters, digits, and hyphens; must start and end with a letter or digit; up to 63 characters total.

Reserved names#

A handful of names are denylisted and can never be bound as a tunnel, chosen or random:

wwwreserved
mailreserved
ns1reserved
ns2reserved
adminreserved
api-edgereserved

Collisions and takeover#

Requesting a name someone else already holds resolves differently depending on who's asking. The rules below apply to normal binds; use --multi-connector when the agents are intentional members of one load-balanced tunnel:

Different instance, holder is liveBindErr
The bind is rejected with subdomain_taken. The agent exits non-zero if you asked for that name explicitly, or retries with a fresh random name if it was auto-assigned.
Different instance, holder is deadTakeover
The new agent takes over the name. The old (zombie) session receives Evicted and is force-closed.
Same instance reconnectingTakeover
Immediate takeover, regardless of whether the old session still looks alive — this is what makes reconnecting after your laptop sleeps feel instant.
Multi-connector modePool
Run every agent with --multi-connector and the same explicit --subdomain. Live connectors share requests; a reconnect replaces only its own connector, and stopping one drains its in-flight requests without taking the other connectors offline. HTTP/2, access-control, and traffic-policy settings must match.