How aliases work

DNS maps a name to an IP address and never to a port. That is the whole problem: myapp.test can be made to resolve, but it will resolve to :80, not to your dev server's :3000. So each alias gets its own loopback address, and a small root process carries port 80 on that address to the port your dev server already listens on.

  /etc/hosts     127.0.0.2   myapp.test
  lo0 alias      127.0.0.2
  forwarder      127.0.0.2:80  ──raw bytes──▶  127.0.0.1:3000

Your dev server is not touched, restarted or reconfigured. It keeps listening on 127.0.0.1:3000 exactly as before; the alias is an addition, not a replacement, and http://localhost:3000 keeps working.

The forwarder splices sockets. It parses nothing — no Host header, no header rewriting, no hop-by-hop rules. That is the KISS choice, and it has consequences worth knowing:

• WebSockets and HMR work for free. Passthrough does not care what the bytes are.
• Any protocol works, not just HTTP.
• There is no proxy in the request path to misinterpret anything, because there is no proxy.

Addresses are allocated from 127.0.0.2 to 127.0.0.254. 127.0.0.1 is never used — it is the real loopback, and your dev server is on it. The lowest free address is assigned when an alias is created and stays with that alias for life, so a name never silently moves.

253 aliases is the hard ceiling, being the size of the pool. The dashboard says so if you ever reach it.

All managed entries live between two markers. Everything outside them — including anything you added yourself — is preserved byte for byte, and the file is written atomically.

# >>> localhost-aliases >>>
127.0.0.2	index.test
127.0.0.3	myapp.test
127.0.0.4	api.myapp.test
# <<< localhost-aliases <<<

Those markers are the uninstall contract. If you ever need to recover by hand, deleting the block between them removes every alias — see troubleshooting.

index.test is always present and maps to the dashboard itself, so Open Dashboard opens a name rather than a port number. It cannot be renamed or deleted from the UI. The dashboard is embedded in the app bundle and listens on 127.0.0.1:7788 by default; it only answers while the app is running.

Every alias ends in .test. RFC 6761 reserves that suffix for development: it is never delegated to a registry, never publicly resolvable, and nothing on macOS claims it — so the line in /etc/hosts is the answer, immediately. Changing the TLD renames every hostname, so the next apply needs one admin prompt.

Reproduce it yourself: time getaddrinfo for a .local name that exists nowhere, and for a .test name that exists nowhere. The first waits, the second returns in microseconds.

bun -e '
const dns = require("node:dns");
for (const n of ["nope-xyz.local", "nope-xyz.test"]) {
  const t = Bun.nanoseconds();
  await new Promise((r) => dns.lookup(n, () => r()));
  console.log(n.padEnd(16), ((Bun.nanoseconds() - t) / 1e9).toFixed(3) + "s");
}'

nope-xyz.local   5.006s
nope-xyz.test    0.003s

.localhost is refused for a third reason: macOS resolves every name under it to 127.0.0.1 on its own and never reads /etc/hosts, so the name would land past the forwarder on a port nothing is listening on.

Settings offers test, internal, lan, home.arpa and example as quick picks, and you can type another. A refused suffix is refused inline, with the specific reason it fails rather than a flat “not allowed”.