pkdns

March 23, 2026 · View on GitHub

A DNS server providing self-sovereign and censorship-resistant domain names. It resolves records hosted on the Mainline DHT, the biggest DHT on the planet with ~10M nodes that services torrents since 15 years.

Getting Started

Hosted DNS

Use one of the hosted DNS servers to try out pkdns quickly.

Verify the server is working.
Configure your browser or system dns.
Browse the self-sovereign web.

Pre-Built Binaries

Download the latest release for your plattform.
Extract the tar file. Should be something like tar -xvf tarfile.tar.gz.
Run pkdns --verbose.
Verify the server is working. Your dns server ip is 127.0.0.1.
Configure your browser or system dns.
Browse the self-sovereign web.

Build It Yourself

Make sure you have the Rust toolchain installed.

Clone repository git clone https://github.com/pubky/pkdns.git.
Switch directory cd pkdns.
Run cargo run --package=pkdns.
Verify the server is working. Your server ip is 127.0.0.1.
Configure your browser or system dns.
Browse the self-sovereign web.

Use Docker Compose

See compose.yaml.

Guides

Use DNS-over-HTTPS in your Browser

Pick a DNS-over-HTTPS URL from our public servers.txt list.
Configure your browser. See this guide.

Verify your server with this domain http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/.

Change your System DNS

Upgrade your whole machine to pkdns by setting it as your primary system DNS.

Follow one of the guides to change your DNS server on your system:

Verify your server with this domain http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/.

Verify pkdns is working

PKDNS Domains

Verify the server resolves pkdns domains. Replace PKDNS_SERVER_IP with your pkdns server IP address.

nslookup 7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy PKDNS_SERVER_IP

Troubleshooting If this does not work then the pkdns server is likely not running or misconfigured.

ICANN Domains

Verify it resolves regular ICANN domains. Replace PKDNS_SERVER_IP with your pkdns server IP address.

nslookup example.com PKDNS_SERVER_IP

Troubleshooting If this does not work then you need to change your ICANN fallback server with pkdns -f REGULAR_DNS_SERVER_IP. Or use the Google DNS server: pkdns -f 8.8.8.8.

Browse the Self-Sovereign Web

Here are some example pkdns domains:

Hint: Always add a ./ to the end of a pkarr domain. Otherwise browsers will search instead of resolve the website.

Address already in use

Other services might occupy the port 53 already. For example, Docker Desktop uses the port 53 on MacOS. systemd-resolved is using it on Ubuntu. Make sure to free those.

Configuration

Options

Usage: pkdns [OPTIONS]

Options:
  -f, --forward <FORWARD>      ICANN fallback DNS server. Format: IP:Port. [default: 8.8.8.8:53]
  -v, --verbose                Show verbose output. [default: false]
  -c, --config <CONFIG>        The path to pkdns configuration file. This will override the pkdns-dir config path
  -p, --pkdns-dir <PKDNS_DIR>  The base directory that contains pkdns's data, configuration file, etc [default: ~/.pkdns]
  -h, --help                   Print help
  -V, --version                Print version