ph-intercept turns Pi-hole DNS query logs into a live, pixel-art space battle. It connects to a Pi-hole v6 instance via its API, streaming queries in real time. Allowed queries appear as friendly ships flying across the screen, while blocked ones spawn as enemy invaders that the central interceptor ship destroys. The project runs as a standalone Docker container, requiring no changes to an existing Pi-hole setup.

This dashboard gamifies DNS monitoring. Frequent domains scale up into larger sprites—heavier transports or capital ships for allowed queries, boss enemies for blocked ones. Controls in the heads-up display (HUD) let users toggle blocking on the fly, set timed blocks, adjust gravity for entities, or swap interceptor ships.

Core features

The dashboard pulls events directly from the Pi-hole v6 API endpoint. Key elements include:

  • Live query rendering: Each DNS query creates a pixel-art entity. Cache-answered queries move faster than upstream ones.
  • Interactive controls: Toggle global blocking, apply timed blocks to domains, trigger gravity pulses, and switch between ship designs via the HUD.
  • Tiered visuals: Entities grow based on recent sightings. Allowed queries progress from small shuttles (green, blue, lime) to capital ships (gold). Blocked ones escalate from crabs and squids (red) to bosses (purple).
  • Custom backgrounds: Options like starfield (with sky presets: summer_triangle, orion, scorpius, southern_cross), dark, nebula, or a custom image URL.
  • Weapon feedback: Ship lasers change color to match enemy tier—green for first blocks, cyan for second, gold for repeated ones.

A screenshot in the repository shows the action: enemies exploding on impact, friendlies streaming by, all against a starry backdrop.

Entity behaviors

Queries spawn entities that traverse the screen left to right. Allowed ones pass harmlessly unless gravity pulls them down. Blocked domains become targets; if the same domain reappears before clearing the screen, it mutates to the next tier sprite on the spot.

Allowed query tiers:

Tier Recent sightings Shapes Colors
1 First Rounded shuttle, Delta wing, X-wing Green, Blue, Lime
2 Twice Heavy transport Cyan
3+ Three or more Capital ship Gold

Blocked query tiers:

Tier Recent blocks Shapes Colors
1 First Crab invader, Squid Red
2 Twice Heavy drone Orange
3+ Three or more Boss Purple

This scaling helps spot repeat offenders visually, without digging into logs.

Getting it running

ph-intercept deploys via Docker Compose, alongside any Pi-hole v6 setup. It needs the Pi-hole app password (found in Pi-hole admin: Settings → Web interface / API → Configure app password), not the web login.

Start with a .env file in your working directory:

PIHOLE_PASSWORD=your_pihole_app_password

Next, create or download compose.yaml from the repo, and edit PIHOLE_URL to match your Pi-hole address (e.g., http://192.168.1.100:80/api):

services:
  ph-intercept:
    image: ghcr.io/m00grin/ph-intercept:latest
    hostname: ph-intercept
    container_name: ph-intercept
    restart: unless-stopped
    env_file:
      - .env
    environment:
      PIHOLE_URL: "http://your.server.ip.address:your_pihole_port/api"
      RETURN_URL: ""
      BG_MODE: starfield
      SKY_PRESET: summer_triangle
      BG_IMAGE: ""
    volumes:
      - ./bg:/app/static/bg:ro
    ports:
      - "4653:4653"

Run docker compose up -d. Access at http://your-host:4653. Press ESC to navigate to RETURN_URL if set (e.g., a homelab dashboard).

For Portainer stacks, set PIHOLE_PASSWORD as an environment variable instead of .env, and comment out the env_file. Custom backgrounds go in /data/compose/<stack-id>/bg/ on the host.

Optional tweaks in compose.yaml: Add DNS servers under dns: for resolution inside the container, or assign a static IP on an external Docker network.

The container exposes port 4653 (change host side if conflicted). No extra dependencies needed beyond Docker and a Pi-hole v6 API endpoint.

Customization

Environment variables control appearance without code changes. BG_MODE picks starfield, dark, or nebula. SKY_PRESET refines starfields. Set BG_IMAGE to a URL or local /bg/filename.jpg path (via the volume mount) to override.

RETURN_URL sets the ESC key target. Leave volumes empty for defaults.

Who this is for

Pi-hole users monitoring homelab or family networks will find it engaging. It suits tinkerers who run Pi-hole on a Raspberry Pi or Docker host and want a glanceable, fun alternative to the standard web dashboard's graphs and tables. Display it on a spare screen via a browser kiosk for real-time DNS traffic visualization—watch ad domains get blasted as they spike.

If you manage DNS blocking for a small setup and enjoy retro games like Space Invaders, this adds personality to query logs. The 51 GitHub stars reflect niche appeal among self-hosters.

Alternatives

Pi-hole's built-in dashboard offers query logs, top domains, and block stats in tables and charts—more data-focused, less visual flair. For heavier monitoring, pair Pi-hole with Prometheus and Grafana via community exporters for customizable graphs.

Other visual tools like DNSCloak provide query maps, but lack the interactive destruction mechanic. Static log viewers such as GoAccess or ELK stack handle high-volume logs without the gamified interface.

ph-intercept stays lightweight at JavaScript-based, Docker-only, unlike fuller suites needing databases.

This 51-star project from m00grin fits playful DNS watchers with Pi-hole v6, not high-stakes production logging. Source at https://github.com/m00grin/ph-intercept.

View on GitHub →