The .test domain & DNS

Butler serves your sites under a top-level domain — .test by default. So a project folder named my-app is reachable at my-app.test, and every subdomain of it (api.my-app.test) resolves too.

How it resolves

During setup, Butler adds a small DNS resolver rule for its TLD. From then on, your Mac sends any lookup ending in .test to Butler’s own DNS, which answers with your local machine — so my-app.test (and anything under it) points at Butler without you editing /etc/hosts for each site. New sites work the instant you link them; there’s nothing to add by hand.

Change the TLD

.test is a good default — it’s reserved for exactly this purpose and will never clash with a real domain. If you’d prefer another suffix, change it:

butler tld dev

Every site immediately moves to the new suffix — my-app.test becomes my-app.dev. Butler updates the DNS resolver and re-issues certificates as needed.

Choose a TLD carefully

Some suffixes are real, public top-level domains (.dev and .app, for instance, are owned by Google and enforce HTTPS). Using one locally can shadow real sites and cause confusing behavior. Butler classifies TLDs and will warn you — or block a clearly unsafe one — when you try to switch. .test is always safe; prefer it unless you have a specific reason not to.

You can set the default TLD during onboarding and change it any time from the app’s settings or with butler tld.