dnscrypt-proxy 2: an encrypted DNS proxy you configure with TOML

What dnscrypt-proxy 2 solves, and for whom

Plain DNS leaves the building unencrypted and unauthenticated. Anyone on the path can read the query and, in many networks, rewrite the answer. dnscrypt-proxy 2 addresses that by acting as a local DNS proxy: applications keep talking ordinary DNS to a local address, and the proxy forwards those queries over an encrypted transport to a remote resolver. The README lists DNSCrypt v2 (including what it calls Post-Quantum DNSCrypt, or DNSCrypt 2026), DNS-over-HTTPS with TLS 1.3 and QUIC, Anonymized DNSCrypt, and ODoH as the supported protocols.

The audience is narrower than "anyone who wants private DNS". This is a tool for people who are comfortable editing a configuration file and thinking about which upstream resolver they trust. The feature list assumes that posture: filtering of ads and malware, time-based filtering with a weekly schedule, transparent redirection of specific domains to specific resolvers, cloaking rules that behave like a HOSTS file with extra logic, and separate log files for regular and suspicious queries. If you only want your browser to stop sending cleartext DNS, a browser-level DoH setting is a smaller change. If you want one process to handle encryption, blocklists, caching and routing for a whole machine or network, this is the shape of tool you are looking for.

How the proxy routes a query: resolvers, stamps and load balancing

The architecture is a forwarding proxy, not a recursive resolver. It does not walk the DNS tree from the root; it picks an upstream server from a list and forwards the query to it over one of the encrypted protocols. That distinction matters when you compare it with something like Unbound, which resolves recursively on its own.

Upstream servers are described by DNS stamps, and the project maintains a separate public resolver list. The README points to dnscrypt.info/public-servers for DNS-over-HTTPS and DNSCrypt resolvers, and to dnscrypt.info/stamps for the stamp format. The proxy can update the resolver lists in the background automatically, which is how the set of usable servers stays current without you editing them by hand.

Selection is dynamic. The README describes load balancing as picking a set of resolvers, measuring and tracking their speed, and balancing traffic across the fastest available ones. The go.mod file shows github.com/VividCortex/ewma, an exponentially weighted moving average library, which is consistent with that description of continuous speed tracking. In practice this means the resolver you actually use can change between queries, which is good for latency and bad for anyone trying to reason about a single upstream's logging behaviour.

Two mechanisms are worth separating. Anonymized DNS and relays hide the client IP from the resolver; Tor and SOCKS proxies are the other route the README lists for the same goal. Caching is separate again, and the README frames it as reducing latency and improving privacy. Filtering and cloaking sit on top of the forwarding path, so a blocked name never reaches an upstream at all.

Installing dnscrypt-proxy 2 and running a first query

The README points to pre-built binaries for a long list of targets: Linux (x86, x86_64, arm, arm64, mips, mipsle, mips64, mips64le), Windows, Windows 64 bit, Windows ARM, macOS x86_64 and arm64, the BSDs, Dragonfly BSD, and Android on arm, arm64, x86 and x86_64. It also points to the installation wiki page for how to use those files and how to verify their signatures. There is a Makefile in the repository for building from source, with build and install targets that place the binary in $PREFIX/bin, defaulting to /usr/local/bin.

make build

That runs go build inside the dnscrypt-proxy directory and writes the binary there. The install target depends on build and copies the result to the install prefix.

sudo make install

The README does not document a default configuration path or a first-run flag, so the practical first step is to obtain a config file and edit it. The configuration format is TOML; go.mod lists github.com/BurntSushi/toml, and people search for "dnscrypt proxy toml" for exactly this reason. The README does not reproduce a full example config, so the configuration reference at dnscrypt.info/doc is where the keys live. After starting the proxy, point a client at the address you configured and query it. If the proxy is running and the resolver name is valid, you get an answer; if the name is not in the resolver list, the proxy has nothing to forward to. The README's own advice is to start at dnscrypt.info/doc, which is where the configuration reference lives.

Where dnscrypt-proxy 2 is the wrong tool

It is a forwarder. If your requirement is to resolve names independently of any third party, this is the wrong process, because every answer comes from an upstream resolver you selected. A recursive resolver answers from the root down and does not delegate that trust.

Hot reloading is off by default from v2.1.10. The README states this directly, and it changes how you operate the service: editing a config file and expecting the running process to pick it up is not the default behaviour. You either restart the service or you turn the option back on deliberately. Deployment tooling that assumes live config reload will silently keep serving the old rules.

The project is a Go binary that expects to own a port. On a system where something else already listens on port 53, the proxy will not start, and the README does not describe a conflict-resolution path. The same applies to the local DoH server it includes for ECH support, which needs its own listener.

Finally, the resolver list is external. Server names, stamps and availability live in a separate repository that the proxy updates in the background. If that source is unreachable at first start and you have no cached list, you have no upstreams. The README does not describe an offline fallback for that case.

dnscrypt-proxy 2 compared with Unbound

Unbound and dnscrypt-proxy 2 overlap on the word "resolver" and almost nothing else. Unbound is a recursive, validating resolver: it starts at the root, follows referrals, and validates DNSSEC itself. dnscrypt-proxy 2 forwards to an upstream over an encrypted transport and, per the README, is compatible with DNSSEC rather than being a validator in its own right.

The difference shows up in what you have to trust. With Unbound, you trust the root zone and your own network path; the queries are in the clear unless you wrap them. With dnscrypt-proxy 2, you trust whichever upstream the load balancer has currently selected, and in exchange the query is encrypted and authenticated in transit. Unbound gives you independence from third-party resolvers; dnscrypt-proxy 2 gives you confidentiality from the local network and from anyone between you and the resolver.

They are also not mutually exclusive in principle, since dnscrypt-proxy 2 can forward to a resolver you run. But the two projects solve different halves of the problem, and picking one because it has "DNS" in the name is how people end up with a setup that does neither job well.

Maintenance, releases and the ISC licence

The repository is not archived, and the last push was on 2026-09-21. Releases are frequent rather than annual: 2.1.18 on 2026-07-18, 2.1.17 on 2026-07-13, and 2.1.16 on 2026-05-24. That cadence means upgrade cost is mostly about configuration drift rather than API churn, since the tool is configured through a file and consumed as a service.

The dependency list is worth reading before you build from source. go.mod requires Go 1.27.0 and pins a large set of modules, including quic-go for QUIC, cloudflare/circl for cryptography, and several libraries maintained by the project's own author (dlog, go-dnsstamps, go-hpke-compact, go-minisign, go-sieve-cache, xsecretbox, go-clocksmith). That concentration is convenient for consistency but means a meaningful part of the supply chain sits with one maintainer. Building from source also requires fetching all of these; the repository vendors them, which is what the vendor target and the distclean target in the Makefile manage.

The licence is ISC, a permissive, short licence. It permits use and redistribution with the copyright notice and licence text retained, and it disclaims warranty. That is a summary of the licence family, not legal advice; if you redistribute the binary or embed it in a product, read the LICENSE file in the repository and get your own counsel.

Editorial conclusion

Adopt dnscrypt-proxy 2 if you already run your own resolver or want encrypted DNS with blocklists, cloaking and per-domain routing in a single Go binary, and you are willing to edit a TOML file. Do not adopt it if you want a daemon that manages your system resolver for you, or if you need a full recursive resolver rather than a forwarding proxy. Before deploying, verify that the resolver names you pick are still published in the public resolver list, that your chosen listen address does not collide with an existing stub resolver on port 53, and that a config change you make is actually reloaded, since hot reloading is disabled by default from v2.1.10.

Frequently asked questions

Official sources

1. DNSCrypt/dnscrypt-proxy on GitHub
2. License: ISC
3. Project website
4. README
5. Releases