ngsrv

Domain Management

Create and manage custom domains for consistent tunnel URLs

Overview

Custom domains (reserved subdomains) allow you to use the same URL across tunnel sessions. Perfect for OAuth callbacks, webhook endpoints, and sharing links with your team.

Domain Format

Reserved subdomains (platform)

Reserved domains are a single DNS label under one of the NGSRV base domains:

<label>.tnl.ngsrv.com<label>.ngsrv.app<label>.ngsrv.dev

BYOD (Bring Your Own Domain)

BYOD domains are hostnames you own (for example api.example.com). They are created and verified in Dashboard → Domains.

List Domains

View all domains available to your account and team:

ngsrv domain list

Example Output:

Available Domains:

✓ myapp (default)

✓ staging

✓ dev-alice

3 domains available

Create Domain

Reserve a platform subdomain for your team. By default the CLI prompts you to pick a base domain interactively; pass --base / -b with a base-domain ID to skip the prompt (useful in scripts).

ngsrv domain create <name>ngsrv domain create <name> --base <base-domain-id>

Domain Naming Rules

  • 1-63 characters long
  • Only lowercase letters, numbers, and hyphens
  • Must start and end with a letter or number
  • No dots (single label only)

Examples

ngsrv domain create myapp

Creates: myapp.<base-domain-you-select>

ngsrv domain create staging-env

Creates: staging-env.<base-domain-you-select>

⚠️ Important

  • • Domains are scoped to your team (all team members can use them)
  • • Only one tunnel can use a domain at a time
  • • Domain names are first-come, first-served globally

Set Default Domain

Set a default domain for your local CLI (so you can omit --domain):

ngsrv domain set-default <name>

Example Workflow

# Set default domain

$ ngsrv domain set-default myapp

✓ Default domain set to: myapp

# Now you can omit --domain flag

$ ngsrv http 3000

✓ Tunnel created at: https://myapp.<your-base-domain>

Note

The CLI stores this preference locally (in ~/.ngsrv/preferences.json). You can also set a default domain from Dashboard → Domains.

Using Domains in Tunnels

Once created, use your custom domain when creating tunnels:

Option 1: Use --domain flag

ngsrv http 3000 --domain myapp

BYOD hostname (full domain)

ngsrv http 3000 --domain api.example.com

Use the full hostname for BYOD entries (created/verified in the dashboard).

Option 2: Set as default

ngsrv domain set-default myappngsrv http 3000

Option 3: Config file

# ngsrv.yml
domain: myapp
port: 3000
ngsrv http

Team Domain Management

Domains are team resources - all team members can see and use them:

Strategy: Per-Developer Domains

Create individual domains for each team member to avoid conflicts:

• myapp-alice.tnl.ngsrv.com

• myapp-bob.tnl.ngsrv.com

• myapp-charlie.tnl.ngsrv.com

Strategy: Environment-Based

Create domains for different environments:

• myapp-dev.tnl.ngsrv.com (development)

• myapp-staging.tnl.ngsrv.com (staging)

• myapp-demo.tnl.ngsrv.com (client demos)

Strategy: Feature-Based

Create domains per feature for parallel development:

• myapp-auth.tnl.ngsrv.com (authentication)

• myapp-payments.tnl.ngsrv.com (payment flow)

• myapp-dashboard.tnl.ngsrv.com (UI work)

Common Use Cases

OAuth Development

OAuth providers require fixed callback URLs:

1. Create domain: ngsrv domain create myapp-oauth

2. Configure OAuth: https://myapp-oauth.tnl.ngsrv.com/callback

3. Start tunnel: ngsrv http 3000 --domain myapp-oauth

Webhook Configuration

Set webhook URLs once and reuse them:

Configure Stripe webhook: https://myapp.tnl.ngsrv.com/webhook/stripe

Start tunnel anytime: ngsrv http 8000 --domain myapp

Team Collaboration

Share stable URLs with team members:

"Check my work at: myapp-alice.tnl.ngsrv.com"

URL stays the same across development sessions

Troubleshooting

Domain Already Taken

Domain names are globally unique. Try adding your company name or team identifier.

Domain Already In Use

Another tunnel is using this domain. Use --force to terminate it or choose a different domain.

Can't See Team Domains

Make sure you're authenticated with the correct account and that your API token has access to the team's domains.

Bring Your Own Domain (BYOD)

BYOD lets you use a hostname you own (for example api.example.com) as the public tunnel URL.

  1. Create the BYOD entry in Dashboard → Domains
  2. Add the TXT record shown (verification)
  3. Click Verify (wait for DNS propagation if needed)
  4. Point a CNAME for your hostname to byod.ngsrv.com
  5. Start a tunnel with --domain set to the full hostname

Plan requirements

Domains are a paid feature and count toward your team’s domain limits. You can view limits and upgrade in Dashboard → Billing.

Next Steps

→ Create HTTP tunnels with custom domains→ Set default domain in config file→ Manage domains in the dashboard