Reserved Subdomains

Overview

Reserved subdomains let you claim stable, memorable tunnel URLs that persist across sessions. Instead of a random subdomain like brave-dolphin-123.tunnels.usejetty.online, you reserve a name like my-api.tunnels.usejetty.online and reuse it whenever you need.

Use cases: webhook development (stable URLs for GitHub, Stripe, etc.), client demos, CI/CD integration testing, and team collaboration.

How It Works

1. Reserve a unique label (e.g., my-api) for your organization
2. The subdomain becomes exclusively yours: my-api.tunnels.usejetty.online
3. Use it with any tunnel via --subdomain=my-api
4. The reservation persists even when tunnels are stopped

Reserved subdomains are organization-wide -- any team member can use them.

Ephemeral vs Reserved

By default, jetty share 8000 assigns a random subdomain that changes each session. Reserved subdomains give you a consistent URL:

jetty share 8000 --subdomain=my-api
# => https://my-api.tunnels.usejetty.online

Reserving a Subdomain

From Dashboard (Recommended)

1. Go to Settings > Domains
2. Under "Reserved Subdomains", enter your desired label
3. Click Add or Reserve

From CLI

The CLI requires you to reserve the subdomain through the dashboard first. This prevents typos from consuming your quota.

jetty share 8000 --subdomain=new-api
# Error: This hostname label is not reserved for your crew.
#  Add it under Domains first, or omit subdomain for a random label.

Naming Rules

• Lowercase letters, numbers, and hyphens only
• Must start and end with a letter or number
• No consecutive hyphens
• Maximum 63 characters
• Pattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Using Reserved Subdomains

# Basic usage
jetty share 3000 --subdomain=my-api

# With explicit host
jetty share 3000 --subdomain=staging-api --host=127.0.0.1

# With health check
jetty share 8080 --subdomain=demo --health-path=/health

Reserved subdomains are portable -- you can point them at different local applications. Just stop the first tunnel before starting the second.

With Custom Domains

Reserved subdomains work alongside custom domains. See the Custom Domains Guide for details.

Plan Limits

Check your usage in Settings > Domains or via jetty domains.

Best Practices

Naming Conventions

Use descriptive, purpose-driven names with lowercase and hyphens:

# Project-environment pattern
shopify-staging
shopify-dev
acme-demo

# Function-based pattern
webhooks-github
webhooks-stripe
demo-sales

Team convention: [team]-[project]-[purpose] (e.g., platform-auth-staging)

Security

Subdomain names are visible in URLs and DNS records. Never include API keys, secrets, confidential project code names, or customer-identifying information.

Common Use Cases

Webhook Development

Reserve a subdomain so you configure the webhook URL once:

jetty share 3000 --subdomain=github-webhooks
# Configure in GitHub: https://github-webhooks.tunnels.usejetty.online/api/github/webhook

The URL stays the same across sessions -- no need to reconfigure after restarting. Reserve dedicated subdomains per provider (github-webhooks, stripe-webhooks, twilio-webhooks).

Client Demos

jetty share 3000 --subdomain=acme-demo
# Every meeting: https://acme-demo.tunnels.usejetty.online

Clients can bookmark the URL. No confusion from changing random subdomains between meetings.

Integration Testing (CI/CD)

# .github/workflows/integration-tests.yml
jobs:
  integration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Start application
        run: npm start &
      - name: Create tunnel
        run: |
          curl -fsSL https://usejetty.online/install/jetty.sh | bash
          jetty share 3000 --subdomain=ci-integration --background
        env:
          JETTY_API_TOKEN: ${{ secrets.JETTY_API_TOKEN }}
      - name: Run integration tests
        run: npm test
        env:
          API_URL: https://ci-integration.tunnels.usejetty.online

Mobile App Development

Hardcode the tunnel URL in your mobile app config -- no rebuilds when the tunnel restarts:

jetty share 8000 --subdomain=mobile-api

Managing Reserved Subdomains

Viewing Reservations

View in Settings > Domains or via jetty domains.

Releasing Subdomains

In Settings > Domains, click Delete next to the subdomain.

Warning: Once released, the name becomes available to any organization. On paid plans with unlimited reservations, keep names you might reuse.

Subdomain Conflicts

If two team members use the same reserved subdomain simultaneously, the second connection takes over routing. Avoid this by:

• Using personal naming (api-staging-alice, api-staging-bob)
• Coordinating via team chat
• Assigning subdomains to specific purposes

Troubleshooting

"Subdomain not reserved" Error

Error: This hostname label is not reserved for your crew.

Reserve it in Settings > Domains first. Check for typos (e.g., my--api vs my-api) and verify you are logged in to the correct organization.

Reached Plan Limit

Error: You have reached the limit of reserved labels for this crew.

Release unused subdomains, upgrade your plan (Coastal/Fleet have unlimited), or use ephemeral subdomains for non-critical cases by omitting --subdomain.

DNS/Resolution Issues

1. Verify tunnel is running (check dashboard > Tunnels)
2. Test DNS: dig my-api.tunnels.usejetty.online
3. Test with curl: curl -v https://my-api.tunnels.usejetty.online
4. Check for conflicts (another team member on same subdomain)
5. Restart the tunnel

Local Application Not Responding ("Bad Gateway")

1. Verify your app is running: curl http://localhost:8000
2. Confirm the correct port in your jetty share command
3. Ensure your app binds to 127.0.0.1 or 0.0.0.0

"Connection Refused"

1. Kill duplicate jetty share processes
2. Check internet connectivity
3. Verify you are logged in: jetty whoami

Getting Help

• Getting Started Guide | Custom Domains | CLI Reference
• Email: support@usejetty.online
• Dashboard: Settings > Help & Support