Open-source project
serverless-dns/serverless-dns avatar
serverless-dns/serverless-dns

serverless-dns is one resolver built four times for four runtimes

The RethinkDNS resolver that deploys to Cloudflare Workers, Deno Deploy, Fastly, and Fly.io

3,851 stars2,276 forksJavaScriptMPL-2.0

At a glance

What is it?
serverless-dns/serverless-dns is a content-blocking stub resolver that runs unmodified on four edge platforms with four different isolation models, and the repository makes that explicit by listing a runtime and a difficulty rating per platform. The readme also documents latency in milliseconds and an authentication scheme built on a keyed hash, which is the part most self-hosters will not need.
Who is it for?
serverless-dns suits someone who wants content blocking on encrypted DNS without running a resolver on their own network, and who will accept that a personal deployment is a free-tier experiment rather than a service. It does not suit someone who needs a locally administered filter.
Can I use it commercially?
Yes, with conditions. MPL-2.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
Is it still maintained?
Activity is slowing. The repository last received commits 6 months ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • serverless-dns/serverless-dns3,851 ★ · +41
Star history
Repository2026-09-242026-11-15
serverless-dns/serverless-dns3.8k3.9k

41 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Four platforms, four isolation models, four difficulty ratings

The self-host table is the most useful thing in the readme because it rates the platforms rather than listing them. Two are marked easy, one moderate and one hard, and the reasons are given as the runtime and the isolation model in the same cell. Two run on isolates, one on a different isolate implementation, and the hard one runs on a full virtual machine. So the choice of platform is really a choice of what you are willing to debug, and the readme tells you which. Running it locally does not need a deploy at all: there is a single run script taking a one-letter argument per platform, one for the Node server, one for the Deno runtime, one for the edge-compute platform and one for the command line client.

bash
./run n

Free tiers of all four are said to be enough for the DNS traffic of somewhere between ten and twenty devices for a month, which is the sizing assumption the project is making.

A blocked lookup never leaves the server

The name in the readme's opening line describes the mechanism: a stub resolver. A stub does not resolve names itself. It answers from a blocklist, returning nothing for names that are blocked and forwarding the rest to an upstream resolver. Because the answer for a blocked name requires no lookup at all, that is the case that costs no money, which is the property that makes a free tier viable for a household. Content blocking is the stated purpose, with the blocklist collection linked as a related project. There is also a configuration page served from the resolver's own domain, so a self-hosted deployment gets its own setup page rather than pointing at someone else's.

Two of the four deployments serve both encrypted protocols

The table of production endpoints lists four platforms with the server count for each, ranging from thirty to more than two hundred, and each row gives the protocol. Three of them serve only the web-based encrypted protocol, and the fourth serves that one plus its stream-based counterpart. Two of the four are marked as a private beta with no public domain listed, so only two endpoints are ones you can point a client at today. Latency is then given twice: server-side processing from nothing to two milliseconds at the median, and end to end from ten to thirty milliseconds at the median, with the explicit caveat that the second varies by region and network. The two public endpoints are the ones with domains listed, and each is reached over the web-based protocol except the fourth, which serves both.

A request passes through three named layers

The development section documents the request flow as a numbered chain, and it is worth reading because it shows the shape of the code. A client talks to one of three server entry points, one per runtime family, which then talk to a core module, which in turn talks to a plugin module. A second chain describes what happens inside that plugin layer: a user-operation handler, then a cache resolver, then a module for handling conditional requests, then the resolver itself. So there is one protocol core and a thin per-runtime shell around it, and the caching sits inside the plugin rather than around the whole service, which is what keeps the edge builds small enough to matter.

One test command that is a placeholder

The manifest's test script is a line that echoes an error saying no test is specified and exits non-zero, and the test script exists in the tree regardless. That is a genuine finding rather than an omission, and it is the kind of detail that matters if you plan to contribute: a change here is not covered by an automated suite, so the pull request checks mentioned in the readme are style checks, not behaviour checks. The readme is otherwise accurate about its process, noting that commits enforce a published style guide through a linter, that a pre-commit hook runs the linter and formatter on script files, and that the hook can be bypassed deliberately when a commit has to land unformatted. Pull requests are checked for style violations too and fixed automatically where the tooling can, so a rejected contribution is far more often a formatting problem than a logic one.

Configuration lives in a different file per platform

There is a core environment file that the readme tells you to edit if you need to change defaults, and then three platform-specific files that override it. The workers platform uses one, the edge-compute platform uses another, and the virtual machine platform uses two of its own, one for the application and one for its transport configuration. The readme is explicit that on those platforms you set the variables in the platform file instead of the core one. So there is a single documented default and four places it can be overridden, and getting that wrong means the resolver starts with defaults it did not choose. There is also a container file per runtime at the repository root, which is the fourth axis of per-platform variation after the configuration file, the bundler configuration and the server entry point.

Authentication is a keyed hash inside an existing field

The auth section is dense and the design is unusual enough to be worth describing rather than paraphrasing. Both encrypted protocols support an alphanumeric bearer token. To build one you take a secret, compute a keyed hash over a fixed message, and append the result to a comma-separated list of keys in an environment variable. The fixed message is a constant rather than something per-user, which means every token for a deployment shares the same input. Where the token goes differs by protocol: appended to a field at the end of a blockstamp for the web-based one, and embedded in the server name field for the stream-based one, using a different delimiter in each case. The readme also warns to keep the secret short if both protocols are used, because subdomains are involved.

Editorial conclusion

serverless-dns suits someone who wants content blocking on encrypted DNS without running a resolver on their own network, and who will accept that a personal deployment is a free-tier experiment rather than a service. It does not suit someone who needs a locally administered filter. Before deploying, pick the platform whose difficulty rating you can meet, note that each runtime has its own configuration file and its own bundler configuration, and remember that the test script in the manifest is a placeholder that exits with an error.

Frequently asked questions

Why are we leaving serverless?

The repository does not discuss that. It deploys a blocking stub resolver to four edge platforms, lists the production endpoints and their server counts, gives server-side and end-to-end latency figures at the median, and marks two of the four deployments as a private beta.

What is serverless vs server?

The readme does not define either term. It explains the isolation model per platform instead, naming isolates for two of them, a different isolate implementation for a third, and a full virtual machine for the fourth, and it rates the setup difficulty of each.

Is 1.1 1.1 DNS the fastest?

The repository makes no comparison with any other resolver. What it reports is its own latency split into server-side processing, from nothing to two milliseconds at the median, and end to end, from ten to thirty milliseconds at the median, with the second stated to vary by region and network.

Is 8.8 8.8 the fastest DNS?

No comparison is offered. What the readme describes is the resolver's own design: it answers blocked names without an upstream lookup, forwards everything else, and can be self-hosted on one of four edge platforms rated from easy to hard, with free tiers said to cover ten to twenty devices for a month.

Official sources

  1. License: MPL-2.0
  2. Project website
  3. README
  4. Releases
  5. serverless-dns/serverless-dns on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/serverless-dns-serverless-dns.svg)](https://hysenlabs.com/projects/serverless-dns-serverless-dns)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/serverless-dns-serverless-dns.svg)](https://hysenlabs.com/projects/serverless-dns-serverless-dns)

Was this useful?