How to Run a Local Handshake (HNS) Node as a Nameserver / Resolver

Learn exactly how to turn your local HNS node (via Bob Wallet or Linux hsd/hnsd) into a working nameserver and recursive resolver for Handshake domains. Step-by-step guide with config examples.

| michelini | 2 min read

Want to resolve Handshake (HNS) names locally without relying on third-party resolvers? You can easily turn a local HNS node into a full nameserver. This guide covers both Bob Wallet (easiest) and direct Linux setups using hsd or hnsd.

Why Run Your Own HNS Nameserver?

Running a local resolver gives you private, censorship-resistant, and faster HNS lookups. It also lets you host authoritative records for names you own.

Option 1: Bob Wallet (Easiest – Includes Full hsd Node)

Bob Wallet bundles the full Handshake node (hsd) and provides a clean GUI for managing names, bidding, and DNS.

  1. Download and install Bob Wallet from bobwallet.io or GitHub releases.
  2. Allow it to fully sync the blockchain (expect tens of GB and some time).
  3. Once synced, Bob Wallet runs hsd in the background.
  4. By default it exposes:
    • Authoritative nameserver on port ~5349
    • Recursive resolver on port ~5350
  5. In your OS network settings, set DNS to 127.0.0.1:5350 (or the exact recursive port shown in Bob settings).

For more control you can run the underlying hsd directly from Bob’s installation folder.

Option 2: Full Node hsd (Linux / Advanced)

hsd is the official full validating node and includes both authoritative and recursive DNS servers.

Installation on Linux

git clone https://github.com/handshake-org/hsd.git && cd hsd\nnpm install\n./bin/hsd --rs-host=127.0.0.1 --rs-port=5350

Key Config Options (hsd.conf or CLI)

# Recursive resolver (recommended for daily use)\nrs-host: 127.0.0.1\nrs-port: 5350\n\n# Authoritative nameserver for your own names\nns-host: 127.0.0.1\nns-port: 5349

Run with:

./bin/hsd --rs-host=127.0.0.1 --rs-port=5350

Testing

dig @127.0.0.1 example.hns +dnssec\ndig @127.0.0.1 -p 5350 google.com

Option 3: Lightweight hnsd (SPV – Low Resources)

Use hnsd if you only need a fast recursive resolver without full chain validation.

git clone https://github.com/handshake-org/hnsd.git && cd hnsd\n./autogen.sh && ./configure && make\nsudo setcap 'cap_net_bind_service=+ep' ./hnsd

Run:

./hnsd -p 4 -r 127.0.0.1:53

Configure Your Operating System to Use the Local Resolver

  • Linux: Edit /etc/resolv.conf → nameserver 127.0.0.1 (use NetworkManager overrides if needed).
  • macOS / Windows: System Settings → Network → DNS → add 127.0.0.1.

Common Tips & Troubleshooting

  • Port 53 usually requires root or setcap.
  • Enable DNSSEC support (built-in).
  • For public recursive service add firewall rules and be careful of amplification attacks.
  • Use systemd, pm2, or Docker for persistent running.

Useful Resources

Once set up, all your applications will resolve .hns domains natively through your own secure local nameserver. Drop a comment with your OS or any errors you hit and I’ll help refine the steps!