dnsshooter

A real-time, space-shooter visualization of your DNS traffic. It streams live DNS query events from your AdGuard Home and renders them as pixel-art friendlies and enemies.

Allowed queries fly past as friendly contacts; blocked queries get intercepted, Space Invaders style. It's a fun way to see your network's DNS activity instead of staring at a stats dashboard.

Credits

Dnsshooter is a fork of ph-intercept by m00grin who created this for Pi-hole. All of the rendering, starfield, splash screen, ship, and game logic come straight from their lovely project. Huge thanks for making it open source. ❤️

The main thing this fork changes is the data source: ph-intercept talks to Pi-hole, dnsshooter talks to AdGuard Home. The frontend assets in static/ are vendored unchanged from upstream; the small Python adapter in app.py and core/ translates AdGuard's API into the Pi-hole-shaped responses the frontend expects.

If you run Pi-hole instead of AdGuard, go use ph-intercept directly — it's the original.

Requirements

• Docker + docker compose
• AdGuard Home running somewhere reachable on your network, with the control API enabled (port 3000 by default — the same port as the AdGuard web UI)
• An admin username + password for AdGuard Home

Quick start

1. Clone this repo and copy the example environment file:

   git clone https://github.com/matthijsbro/dnsshooter.git
   cd dnsshooter
   cp example.env .env

2. Edit .env and fill in your AdGuard Home URL and credentials. See the comments in example.env for guidance — the most common cases are:

   Where AdGuard Home runs	ADGUARD_URL
   Same Docker host as dnsshooter	http://host.docker.internal:3000/control
   A different machine on your LAN	http://192.168.x.x:3000/control
   Over a VPN / WireGuard tunnel	http://10.x.x.x:3000/control

   If youre Adguard runs on another (local) ip address and/or port, change ip:port to yours.

3. Build and start:

   docker compose up -d --build

4. Open http://localhost:4653 and start browsing — you'll see queries appear as you generate DNS traffic.

Configuration

All configuration is via environment variables. The required ones live in .env; the cosmetic ones are set directly in compose.yaml:

Variable	Default	Description
ADGUARD_URL	http://host.docker.internal:3000/control	AdGuard Home control API base URL
ADGUARD_USERNAME	admin	AdGuard Home admin username
ADGUARD_PASSWORD	(none)	AdGuard Home admin password — required
BG_MODE	starfield	Background style: starfield, dark, or nebula
SKY_PRESET	summer_triangle	Sky region (when BG_MODE=starfield): summer_triangle, orion, scorpius, southern_cross
BG_IMAGE	(empty)	Optional custom background image (URL or /bg/your-file.jpg). Overrides BG_MODE.
RETURN_URL	(empty)	Where the ESC key navigates (e.g. your homelab dashboard). Empty = ESC disabled.

To use a custom background image, drop it into the bg/ folder next to compose.yaml (it gets mounted into the container at /app/static/bg/) and set BG_IMAGE=/bg/your-file.jpg.

Useful commands

# Tail logs
docker compose logs -f dnsshooter

# Rebuild after editing Python or templates
docker compose up -d --build

# Stop and remove
docker compose down

License

MIT — see LICENSE. Original copyright © 2026 m00grin (ph-intercept). This fork is released under the same terms.