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.sitePass --subdomain (or its shorthand -s) to request a specific one instead:
$ ngstone port 3000 --subdomain demo→ https://demo.ngstone.siteNaming 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:
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.