Domain Routing & HTTPS

Corral gives every project a custom local domain — like my-worker.test — with automatic HTTPS. No more juggling localhost port numbers.

How It Works

When you visit my-worker.test in your browser, the request flows through:

my-worker.test
  → macOS resolver sends DNS query to dnsmasq (127.0.0.1:5353)
  → dnsmasq resolves *.test → 127.0.0.1
  → Caddy on port 443 terminates HTTPS, reads the Host header
  → Reverse-proxies to wrangler dev on localhost:8787

Three services make this work:

• dnsmasq — a lightweight DNS server that resolves all *.test domains to 127.0.0.1
• Caddy — a reverse proxy that routes requests to the correct project based on the hostname, with automatic HTTPS
• macOS resolver — a system-level file (/etc/resolver/test) that tells macOS to use dnsmasq for .test lookups

The .test TLD

Corral uses .test as the default top-level domain. This TLD is reserved by IANA specifically for testing and development — it will never resolve to a real website.

Each project gets a subdomain based on its name:

Project Name	Local Domain
my-worker	my-worker.test
auth-service	auth-service.test
My Cool App	my-cool-app.test

You can override a project's subdomain:

corral project set my-worker subdomain api
# Now accessible at: api.test

Changing the TLD

You can switch to a different TLD in settings:

corral settings set tld localhost

Or set a custom value:

corral settings set tld dev

WARNING

Some TLDs can cause issues:

• .dev and .app — browsers enforce HSTS (HTTP Strict Transport Security), which may conflict with local certificates
• .local — used by Bonjour/mDNS on macOS, which can interfere with DNS resolution

.test and .localhost are the safest choices.

When you change the TLD, Corral reconfigures DNS and the reverse proxy automatically. All projects switch to the new TLD.

Automatic HTTPS

Caddy generates locally-trusted HTTPS certificates automatically. When you visit https://my-worker.test, Caddy:

1. Generates a certificate signed by its built-in local CA
2. Serves the certificate to your browser
3. Proxies the request to your running worker

No manual certificate setup is required.

Managing Infrastructure

Start and stop DNS and proxy services independently:

# Start infrastructure only (without starting projects)
corral infra start

# Check status
corral infra status

# Stop infrastructure
corral infra stop

Or let corral up and corral down handle both infrastructure and projects together.

The Privileged Helper

DNS and proxy services require elevated privileges on macOS (writing to /etc/resolver/, binding to ports 80/443). Corral handles this through a privileged helper daemon:

• Installed on first launch via the setup wizard, or later from Settings
• Runs only when infrastructure is active — not a persistent background service
• Can be uninstalled at any time from the macOS app's Settings

The helper manages:

• Writing and removing the resolver file at /etc/resolver/{tld}
• Starting and stopping dnsmasq
• Starting and stopping Caddy

The Resolver File

macOS uses files in /etc/resolver/ to override DNS resolution for specific domains. Corral creates:

# /etc/resolver/test
nameserver 127.0.0.1
port 5353

This tells macOS to send all .test DNS queries to dnsmasq on 127.0.0.1:5353. The file is created when infrastructure starts and removed when it stops.

Troubleshooting

Domain doesn't resolve

1. Check that infrastructure is running: corral infra status
2. Verify the resolver file exists: cat /etc/resolver/test
3. Check that the privileged helper is installed (Settings → Infrastructure → Background Service)
4. Try flushing the DNS cache: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

Port 80 or 443 in use

If another service (like Apache or nginx) is using ports 80 or 443, Caddy won't be able to start. Stop the conflicting service before starting Corral's infrastructure.