IndigoStack

Domain Resolution

Every site you run in Indigo is reached through its domains — but a domain only works once your Mac knows it should resolve to itself (that is, to localhost). This page explains how Indigo handles that for you, and what to do if you’d rather handle it yourself.

The default: Indigo manages your hosts file

Out of the box, the Automatically manage hosts file setting (Preferences → Advanced) is switched on, and Indigo takes care of everything:

  • Just before your stacks start, Indigo adds an entry to /etc/hosts for every domain your running sites use — both IPv4 and IPv6 — so they resolve straight to your Mac.
  • Each entry is tagged # Managed by Indigo., and Indigo only ever touches its own tagged lines. Anything else in your hosts file is left exactly as it was.
  • Before making changes, Indigo saves a backup of your hosts file to /etc/hosts-backups.
  • When your stacks stop, Indigo’s entries are cleaned up again.

The writes are performed by Indigo’s privileged helper, so there’s no password prompt each time a stack starts.

Indigo also maintains a copy of its entries at ~/.indigo/hosts, which is handy as a reference — it always reflects the full list of domains Indigo currently expects to resolve.

Managing domains yourself

If you’d rather Indigo kept its hands off /etc/hosts — for example, because you run your own local DNS — switch Automatically manage hosts file off. (Indigo will ask to restart the System stack when you change this setting.)

From then on:

  • Indigo no longer writes to /etc/hosts. It only maintains the reference list at ~/.indigo/hosts.
  • You are responsible for making every Indigo domain resolve to your Mac. The two common approaches:
    • copy the entries from ~/.indigo/hosts into /etc/hosts yourself, or
    • run a local DNS resolver such as dnsmasq, and point your chosen domains (or a whole wildcard, e.g. *.test) at 127.0.0.1.

The wildcard-DNS approach pairs nicely with keeping all your sites on one domain suffix — no per-site entries needed, ever.

When a domain isn’t resolving

If your browser can’t reach a site that Indigo says is running:

  1. Check the domain resolves to your Mac. Run ping -c 1 yourdomain.test in Terminal — you should see 127.0.0.1 (or ::1). If you get an unknown-host error or a public IP address, resolution is the problem.

  2. Check the hosts entry exists. With automatic management on, /etc/hosts should contain a line for the domain tagged # Managed by Indigo. — if it’s missing, restart the stack so Indigo rewrites its entries. With automatic management off, compare /etc/hosts (or your DNS setup) against ~/.indigo/hosts and fill in whatever’s missing.

  3. Flush the DNS cache if a recently-added domain still isn’t resolving:

    sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

  4. Check for interference. VPN clients and some corporate DNS configurations can bypass /etc/hosts entirely. If a domain resolves correctly with the VPN off but not on, you’ll need to exclude your local domains in the VPN’s settings, or choose a domain suffix your VPN doesn’t capture.