How to Use Subdomains on localhost for Local Development

**The fastest way to use subdomains on localhost: just use *.localhost.** Modern browsers resolve any app.localhost, api.localhost, or tenant1.localhost to 127.0.0.1 automatically, with zero configuration. When you need a custom domain shape, HTTPS, or routing to different ports, map fixed subdomains in the hosts file, or use dnsmasq for wildcards. Here are all three approaches and when to pick each.

Option 1 — Free *.localhost subdomains (no setup)

Per RFC 6761, localhost and everything under it is reserved for loopback. Chrome, Edge and Firefox resolve any *.localhost name to 127.0.0.1 without any hosts edit or DNS config:

http://app.localhost:3000
http://api.localhost:3000
http://tenant-acme.localhost:3000

This is ideal for multi-tenant or subdomain-routed apps: your server reads the Host header and serves the right tenant, while every subdomain points at the same local server. No admin rights, nothing to clean up later. To understand the underlying name, see what is localhost?.

Caveats:

• It always resolves to 127.0.0.1 — you cannot point a subdomain at a different IP this way.
• Some older tools/runtimes do not honor *.localhost; if a non-browser client fails, fall back to Option 2.

Option 2 — Fixed subdomains via the hosts file

When you want a custom TLD (e.g. .test) or need the name to resolve outside the browser, list each subdomain in the hosts file:

127.0.0.1 myproject.test
127.0.0.1 app.myproject.test
127.0.0.1 api.myproject.test
127.0.0.1 admin.myproject.test

You can also group names on one line: 127.0.0.1 app.myproject.test api.myproject.test. The hosts file matches exact names only — there is no pattern matching — so add a line per subdomain. See how to edit the hosts file and the hosts file syntax guide. Prefer .test over .local (which collides with mDNS/Bonjour): which TLD to use for local development.

After editing, flush DNS so the new names resolve immediately (e.g. ipconfig /flushdns on Windows, or the macOS/Linux equivalent).

Option 3 — Wildcard subdomains with dnsmasq

If subdomains are dynamic or too many to list (tenant-1, tenant-2, … or generated per PR), the hosts file is the wrong tool. Use dnsmasq to resolve a domain and all its subdomains with one rule:

# macOS (Homebrew)
brew install dnsmasq
echo 'address=/myapp.test/127.0.0.1' >> $(brew --prefix)/etc/dnsmasq.conf
sudo brew services start dnsmasq
sudo mkdir -p /etc/resolver
echo 'nameserver 127.0.0.1' | sudo tee /etc/resolver/test

Now anything.myapp.test resolves to 127.0.0.1 without touching the hosts file. Full Linux steps and verification: wildcard local domains with dnsmasq.

Which approach should you use?

• Just need many subdomains on 127.0.0.1, in the browser? Use *.localhost (Option 1).
• A few fixed subdomains, custom TLD, or non-browser clients? Hosts file (Option 2).
• **Dynamic/unbounded subdomains, or HTTPS for *.myapp.test?** dnsmasq (Option 3), plus a wildcard mkcert certificate.

Routing subdomains to different ports

DNS only maps a name to an IP, not a port. To serve app.myproject.test and api.myproject.test from different backends on one machine, put a reverse proxy (Caddy, nginx, Traefik) in front on port 80/443 that routes by Host header to each app's port. The subdomains all resolve to 127.0.0.1; the proxy does the rest.

Common pitfalls

• Subdomain refuses to connect: the name resolved but the server is not listening or does not accept that host. Check the port and the dev server's allowed-hosts setting — see localhost refused to connect.
• HTTPS warning on a subdomain: the certificate must cover it; generate mkcert myproject.test "*.myproject.test".
• Old IP after changes: flush DNS and the browser host cache.

For everyday fixed mappings, Locahl manages hosts entries with safe per-project toggles and automatic DNS flushing, so subdomains stay tidy and you only reach for dnsmasq when you truly need wildcards.

_Last tested: June 2026 on Windows 11, macOS 26 Tahoe and Ubuntu 24.04._

Sources and further reading

• RFC 6761 — Special-Use Domain Names (IETF)
• dnsmasq documentation
• The hosts file explained (Wikipedia)