A sleek, self-hosted web dashboard for Blocky — monitor your DNS blocking, run queries, and manage your instance from any browser.
Blocky Visor is an open-source single-page application that gives you full visibility and control over your Blocky DNS proxy and ad blocker. It connects directly to Blocky's REST API and Prometheus metrics endpoint, providing real-time stats, interactive DNS lookups, and one-click management — all from a lightweight static site you can host anywhere.
Dashboard — Live overview of your DNS traffic with auto-refreshing stats: total queries, block rate, cache hit rate, average latency, response breakdown by category, and per-client query counts.
DNS Query Tool — Run manual DNS lookups (A, AAAA, CNAME, MX, and more) through Blocky and inspect the results. Query history is saved locally for quick re-runs.
Blocking Control — Toggle ad/tracker blocking on or off with an optional auto-re-enable timer and per-group control.
List Management — View denylist entry counts per group and trigger a list refresh from configured sources.
Cache Management — Monitor cache entries, hit/miss rates, and flush the DNS cache when needed.
Settings — Configure the Blocky API URL at runtime (no rebuild required), adjust polling intervals, and connect an optional sidecar for advanced features.
Blocky Visor includes an optional Go sidecar service that runs alongside Blocky on the same host. It unlocks three additional pages:
- Analytics — Historical query analytics integrated into the dashboard via a global Live/Historical mode toggle, with hourly and daily breakdowns, top queried/blocked domains, per-client stats, and response category charts across configurable date ranges.
- Query Logs — Paginated, filterable raw query log viewer.
- Config Editor — Read and edit Blocky's
config.ymlwith YAML validation, automatic backups, and one-click service restart.
Platform compatibility: The sidecar runs on any platform that Go supports (Linux, macOS, FreeBSD, etc.). However, the service status and restart features require a Linux system with systemd (e.g. Debian, Ubuntu, Fedora, Arch). On systems without systemd, all other sidecar features (analytics, logs, config editing) work normally.
- A running Blocky instance (v0.24+) with the REST API enabled on port 4000
- Prometheus metrics endpoint enabled in your Blocky config (for dashboard stats)
Blocky Visor is a fully static SPA — just build it and serve the files from any web server.
# Clone the repository
git clone https://github.com/JCHHeilmann/blocky-visor.git
cd blocky-visor
# Install dependencies (Node.js >= 22)
npm install
# Build static files
npm run buildThe output in build/ can be served by any web server (Nginx, Caddy, Apache, etc.). Make sure to configure a fallback to index.html for SPA routing.
Nginx example:
server {
listen 80;
server_name blocky-visor.local;
root /var/www/blocky-visor;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}Caddy example:
blocky-visor.local {
root * /var/www/blocky-visor
try_files {path} /index.html
file_server
}
npm run build
npm run previewThis starts a local preview server for the production build at http://localhost:4173.
Once loaded in the browser, go to Settings and enter your Blocky API URL (e.g., http://192.168.1.100:4000). The URL is saved in your browser's localStorage — no rebuild needed to change it.
To enable Analytics, Logs, and Config pages, deploy the Go sidecar on the same machine as Blocky:
cd sidecar
# Copy and edit the config
cp config.example.yaml config.yaml
# Edit config.yaml — set your API key and CORS origins
# Build and run
go build -o blocky-visor-sidecar .
./blocky-visor-sidecarconfig.yaml example:
listen: ":8550"
api_key: "your-secret-api-key"
cors_origins:
- http://blocky-visor.local
- http://localhost:5173
blocky:
dir: /opt/blocky
# service_name: blocky # systemd service name (default: "blocky")
# config_path: ... # override if non-standard
# log_dir: ... # override if non-standardThe service_name option controls which systemd unit the sidecar manages (status checks and restarts). It defaults to "blocky". If Blocky is not managed by systemd on your system, you can ignore this setting — the sidecar will detect that systemd is unavailable and disable service management gracefully.
Then in Blocky Visor's Settings page, enter the sidecar URL and API key.
# Clone the repo
git clone https://github.com/JCHHeilmann/blocky-visor.git
cd blocky-visor
# Install dependencies
npm install
# Start the dev server
npm run devThe dev server runs at http://localhost:5173 with hot module replacement.
| Command | Description |
|---|---|
npm run dev |
Start dev server with HMR |
npm run build |
Build static files to build/ |
npm run preview |
Preview the production build |
npm run check |
Run svelte-check for type errors |
- SvelteKit with
adapter-static(SPA mode) - Svelte 5 runes (
$state,$derived,$effect) - TailwindCSS v4 via
@tailwindcss/vite - TypeScript throughout
src/
├── lib/
│ ├── api/ # Fetch wrapper + endpoint modules
│ ├── stores/ # Svelte 5 rune-based stores
│ ├── components/
│ │ ├── layout/ # AppShell, Sidebar, Header
│ │ ├── ui/ # Reusable primitives (Button, Card, Toggle, Modal, etc.)
│ │ ├── dashboard/ # Dashboard-specific components
│ │ ├── query/ # DNS query form and results
│ │ ├── analytics/ # Charts and log viewer
│ │ └── settings/ # Settings forms
│ ├── utils/ # Prometheus metrics parser, formatters
│ └── types/ # TypeScript interfaces and error classes
├── routes/ # Pages: /, /query, /lists, /cache, /settings,
│ # /logs, /config
└── app.css # TailwindCSS v4 theme config
sidecar/ # Optional Go sidecar service
Blocky Visor communicates with Blocky's REST API (no auth, port 4000 by default):
| Endpoint | Method | Description |
|---|---|---|
/api/blocking/status |
GET | Blocking status |
/api/blocking/enable |
GET | Enable blocking |
/api/blocking/disable |
GET | Disable blocking (supports ?duration= and ?groups=) |
/api/query |
POST | DNS query ({ query, type }) |
/api/lists/refresh |
POST | Re-download blocking lists |
/api/cache/flush |
PUT | Flush DNS cache |
/metrics |
GET | Prometheus metrics |