Sinkhole
Run a node. Trackers and drainers die at DNS.
Sinkhole is a small DNS resolver you run at home or on a server, the way people run a Pi-hole. It answers every lookup on your network, drops the domains on its list before the browser can connect, and shares verdicts with every other Sinkhole node through a peer swarm. It is the part of PayHole that keeps pockets safe from payment drainers, and it works on its own as a network-wide blocker.
What you get from running one
Protection
Every device on your network
Phones, laptops, TVs, and consoles use it as their DNS server, so blocked domains never resolve. Nothing to install on the devices themselves.
The swarm
Verdicts from every other node
When enough separate operators flag a domain, your node blocks it within seconds. You benefit from reports you never made, and others benefit from yours.
Visibility
A dashboard with the numbers
Queries per minute for 24 hours and 7 days, blocked share, clients, top domains, query types, upstreams, and a live query log. Yours only, never sent anywhere.
Lists
Public blocklists too
Subscribe to hosts-format lists such as the well known ad and tracker sets and Sinkhole refreshes them daily, so it can replace an ad blocker at the network level.
Control
Your box, your rules
Manual entries, a token-protected admin API, exports in hosts, dnsmasq, plain, and JSON formats. Everything stays on the device.
A seat at the table
Reporting rights with a tier
Burning PAYHOLE through the BurnVault unlocks a tier for your operator wallet. From tier one your node can report domains into the swarm, not just receive.
What you do not get: money. Nobody is paid for running a node, there are no emissions, no rewards, and no share of anything. PAYHOLE is only ever bought and burned. The return on running Sinkhole is a network that is safer for you and for everyone else on it, and the standing to help decide what gets blocked.
How to run it
Tested on a Radxa Rock Pi and an NVIDIA Jetson, both 64-bit ARM, and on an x86 VPS. Any always-on Linux box with Docker works: a Raspberry Pi 4 or 5 on the 64-bit OS, a NAS, a mini PC, a VPS. Two gigabytes of memory are enough. The running container uses about 120 MB before you add lists.
01
Install Docker
Docker's install script works on Debian, Ubuntu, and Raspberry Pi OS. Add your user to the docker group so you do not need sudo, then log out and back in.
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
02
Get the code and write the settings
One file holds every setting. The admin token protects the dashboard and the API; generate a long one.
git clone https://github.com/S4PAY/payhole.git
cd payhole/packages/sinkhole
cp .env.example .env
sed -i "s|^ADMIN_TOKEN=.*|ADMIN_TOKEN=$(openssl rand -hex 32)|" .env
Then open .env and set two lines: ADMIN_BIND to the box's address on your network so you can open the dashboard from your phone, and DNS_HOST_PORT to 5335 if something else already owns port 53 on the box, for example Pi-hole or systemd-resolved.
03
Start it
The home compose file publishes DNS to the whole network and keeps the admin page on the address you chose.
docker compose -f docker-compose.home.yml up -d --build
On a box whose Docker daemon is older than its compose plugin, Debian 12 ships one like that, build directly and let compose only run it:
DOCKER_BUILDKIT=0 docker build -f packages/sinkhole/Dockerfile -t payhole-sinkhole ../..
docker compose -f docker-compose.home.yml up -d --no-build
The first build takes about fifteen minutes on a Rock Pi. If you run several nodes, build once and copy the image with docker save and docker load.
04
Open the dashboard
Browse to http://your-box-address:8053, paste the admin token, and press Connect. The status cards work even before the token; the tabs fill in after. Check that the Resolver card says running.
05
Point your network at it
Two ways. Set your router's DHCP DNS server to the box's address and every device follows on its next lease. Or, if you already run Pi-hole on the same box, keep it in front: in Pi-hole's DNS settings, untick the upstream servers and add the box's address followed by #5335 as a custom upstream. Pi-hole keeps its ad lists, Sinkhole adds the drainer list behind it, and nothing on your devices changes.
Check it from any machine on the network: a normal name resolves, a name on the blocklist answers 0.0.0.0.
06
Add lists
In the Lists tab, paste a hosts-format URL and subscribe. The unified StevenBlack list is the usual first one. Sinkhole fetches it, loads it into the resolver, and refreshes it every day. Watch the Resolver reloads card and the box's memory before stacking several large lists on a small board.
07
Join the swarm
SWARM_ENABLED is on by default. Give the node a bootstrap peer in SWARM_BOOTSTRAP: the address of another node you run, or the public PayHole node: /dns4/swarm.payhole.org/tcp/4001/p2p/12D3KooWMVhpReYWrsgv5QJLqfKMeULHsFqpgjAHRf9nA9Req1Nr. It relays and verifies but never reports, and it accepts flags only from wallets holding a tier. Nodes behind home routers connect outbound and need no port forwarding; forward TCP 4001 only if you want to accept inbound peers. Every node receives and applies the swarm's verdicts. A domain is blocked once FLAG_THRESHOLD separate operators have flagged it; the default is five.
08
Report, with a tier
Receiving is open to everyone. Reporting needs an operator identity with a tier: put a wallet's private key in NODE_OPERATOR_KEY, or keep the key off the box and use NODE_OPERATOR_ADDRESS plus a proof signed offline, then burn PAYHOLE through the BurnVault from that wallet to reach tier one. MIN_TIER on every node decides the minimum tier a reporter must hold before their flags count, so a swarm cannot be flooded by throwaway wallets.
Good to know
Everything the node knows stays on the node: the query log, the stats, the lists. The only things that leave are swarm messages, which carry a domain, a reason, and a signature, never your queries.
The admin page and API are protected by the token and bound to the address you chose. Keep them on your network. Port 53 open to the LAN is the point; nothing needs to be open to the internet.
Ports: 53 or 5335 for DNS, 8053 for the dashboard, 4001 for the swarm. Data lives in a Docker volume, so updates keep your lists, flags, and history. To update, pull the repository, rebuild, and restart the container.
The full reference, every setting, and the multi-node procedure are in the Sinkhole README. Pi-hole and Sinkhole are different tools that work together: Pi-hole blocks ads from public lists, Sinkhole blocks drainers from a live swarm and can carry the same public lists.
le