First run
What the onboarding does, what the one admin prompt changes, and when it comes back.
The five steps
Onboarding runs once at first launch and is re-runnable from Settings. Every step shows its real state, never an optimistic one.
- 1What will change on this Mac. The exact hostnames, loopback addresses and file paths are listed before anything happens. Nothing has run yet.
- 2Apply to this Mac. One macOS admin prompt. This is the only step that needs your password.
- 3Verify it actually works. The app fetches
http://index.testfor real and reports what came back, rather than assuming the previous step worked. - 4HTTPS for the dashboard — optional. Generates a local certificate authority and trusts it in your *login* keychain, so
https://index.testworks. This is for the dashboard alone. - 5MCP server for your coding agents — optional. One click installs it into Claude Code or Codex. See MCP.
What the admin prompt actually does
The prompt is raised by osascript … with administrator privileges and runs a single script, packages/privileged/apply.sh, which ships in the bundle at Contents/Resources/privileged/apply.sh. You can read it before you type your password. It takes a desired-state JSON file, is idempotent, and does exactly four things:
- 1Adds the loopback addresses your aliases need to
lo0(ifconfig lo0 alias 127.0.0.2), and removes the ones it previously added that are no longer wanted. - 2Rewrites the managed block in
/etc/hosts, atomically. Everything outside the markers is preserved byte for byte. - 3Flushes DNS (
dscacheutil -flushcache,killall -HUP mDNSResponder), so the new names resolve immediately. - 4Starts the raw TCP forwarder as root, detached, if it is not already running.
Nothing is permanently installed
SMAppService, no privileged helper tool and no sudo installer. The only changes to the machine are the /etc/hosts block and the lo0 addresses, and both are reversed by uninstalling.When the prompt comes back
| Action | Prompts? |
|---|---|
| Add an alias | Yes — a new hostname and a new loopback address |
| Delete an alias | Yes — the address and the hosts line come back out |
| Change an alias's target port | No. The forwarder watches its routes file and reloads |
| Rename an alias, or change the TLD | Yes — every hostname changes |
| Launch after a reboot | Once, if the reboot cleared the lo0 addresses |
| Quit the app | No |
A reboot clears lo0 aliases, so the app checks the live state at launch and only prompts when it has actually drifted from what you configured.
How a root process is stopped without root
The forwarder runs as root, and a normal user process cannot kill root. So the forwarder owns its own lifetime: the app touches a liveness file every 5 seconds, and the forwarder exits by itself once that file has been stale for 15 seconds. Quitting the app is therefore clean, with no second password prompt and nothing left running.
the heartbeat
~/.config/localhost-aliases/liveness