dnscrypt-proxy on macOS: Homebrew, Manual Install and DNS Settings

Route one: dnscrypt-proxy on macOS through Homebrew

Homebrew’s formula tracked release 2.1.20 within days, so the package manager is the shortest path to a current build. The formula installs the binary under the Homebrew prefix, keeps the configuration file in its etc folder, and defines a service that requires root because it must bind to port 53. Start it with sudo, or it will fail.

brew install dnscrypt-proxy
sudo brew services start dnscrypt-proxy

The formula’s notes describe the defaults: the proxy listens on 127.0.0.1 port 53 and balances queries across a set of resolvers. Settings live in dnscrypt-proxy.toml inside the prefix’s etc folder, which is /opt/homebrew/etc on Apple Silicon. Edit that file, then run sudo brew services restart dnscrypt-proxy to apply changes. Upgrades come with brew upgrade like any other formula.

Which route suits you is mostly a question of habit. Homebrew users get updates alongside their other tools and never handle a plist. The zip route suits people who want the binary, the TOML file, the lists and the logs in one visible folder, and who prefer to decide themselves when a new release replaces the old executable.

Route two: the release zip

The manual route follows the project wiki. Download macos_arm64 for Apple Silicon or macos_x86_64 for Intel from the releases page, verify it with Minisign as the installation hub explains, and extract it into a folder you will keep, for example in your home directory or under /Applications. Leave the DNS settings untouched for now.

1. Open Terminal and get a root shell with sudo -s.
2. cd into the extracted folder and check that ls -l lists the binary and the example file.
3. Run cp example-dnscrypt-proxy.toml dnscrypt-proxy.toml.
4. Start it in the foreground with ./dnscrypt-proxy and watch the notice lines.
5. Open a second window with Command-N and run ./dnscrypt-proxy -resolve example.com.
6. Stop the foreground copy with Control-C and run ./dnscrypt-proxy -service install, then -service start.

The service installer writes a launchd file at /Library/LaunchDaemons/dnscrypt-proxy.plist and assumes the executable and its configuration share a folder. If you split them, you have to add the -config option to that plist yourself. Upgrading means checking the running build with -version, replacing only the executable with the new one, and restarting the service.

Setting DNS in System Settings or with networksetup

Apple’s current path is Apple menu, System Settings, Network in the sidebar, then the active service (usually Wi-Fi), Details, and DNS. Note the existing servers, remove them with the minus button, add 127.0.0.1 with the plus button and click OK. The wiki suggests that nervous first-timers may keep a public server below it as a fallback.

The same change works from Terminal, which is handy on several Macs or inside a script. The networksetup tool lists services, sets their DNS servers, and clears them again when you pass empty instead of an address. Service names must match exactly what the list prints, including capital letters and spaces, so copy them rather than typing from memory.

networksetup -listallnetworkservices
sudo networksetup -setdnsservers Wi-Fi 127.0.0.1
sudo networksetup -setdnsservers Wi-Fi empty

Checking that dnscrypt-proxy on macOS works

Run ./dnscrypt-proxy -resolve example.com from the install folder (or the Homebrew binary under opt/dnscrypt-proxy/sbin). The output names the resolver that answered and whether the zone is DNSSEC signed. The Homebrew notes add a second test: watch port 443 with sudo tcpdump -i en1 -vvv 'port 443' (with your interface in place of en1) to see resolver traffic.

For a check that does not rely on the proxy reporting on itself, use the commands on the DNS leak check page. They ask outside services which resolver reached them, and the answer should be a server from your list, never your network. That matters most on hotel and café connections, covered on the public Wi-Fi page.

Fixing Mac DNS issues after the switch

Most Mac DNS issues after installing dnscrypt-proxy on macOS fall into a handful of patterns, and the error text usually tells you which one you hit. Work through them in order before touching the configuration, because a changed setting on top of an unresolved conflict only makes the log harder to read.

• bind: permission denied: the shell is not root; use sudo -s or start the Homebrew service with sudo.
• bind: address already in use: something else holds port 53 (see below), or an older copy is still running.
• dnscrypt-proxy.toml: no such file or directory: the example file was never copied.
• bare keys cannot contain '\n': a syntax error in the TOML file.
• No DNS at all: remove 127.0.0.1 from the DNS list to get back online, then investigate.

The stubborn case is mDNSResponder. Its DNS proxy grabs port 53 whenever Internet Sharing is on or an app using the native hypervisor runs, such as Docker. Disabling it means editing a plist under /System, which requires turning off System Integrity Protection. The gentler workaround is moving the proxy to another port and redirecting 53 with a firewall rule.

Security software is the other source of friction. Little Snitch raises several alerts during installation, which must be allowed permanently, and Drive Pulse may report the new launch daemon. Neither indicates a problem with dnscrypt-proxy on macOS itself. After any macOS update, glance at the DNS list again: updates and VPN clients occasionally restore the previous servers without asking.