Blocky Home Assistant Add-On

A powerful DNS proxy and ad-blocker for your Home Assistant ecosystem.

About

This repository contains a Home Assistant add-on that packages Blocky, a fast and lightweight DNS proxy and ad-blocker. Blocky provides network-wide ad blocking, privacy protection, and advanced DNS features for your entire network through a single Home Assistant add-on.

Key Features

• Network-Wide Ad Blocking - Block ads, trackers, and malicious domains across all devices
• Modern DNS Protocols - Support for DNS-over-TLS (DoT) and DNS-over-HTTPS (DoH)
• Multiple Upstream Resolvers - Configure multiple DNS providers with intelligent query distribution
• Split-DNS / Conditional Routing - Route specific domains to designated DNS servers
• Custom DNS Mappings - Define local hostname-to-IP mappings without upstream forwarding
• Client Groups & Identification - Apply different blocking rules per device or client
• Query Logging - Record DNS queries to CSV, MySQL, PostgreSQL, or console
• Redis Integration - Synchronize cache across multiple Blocky instances
• Prometheus Metrics - Built-in monitoring endpoint for observability
• HTTP API - Programmatically control blocking, test queries, and refresh blocklists
• Smart Caching - DNS response caching with prefetching support

Quick Start

This add-on can be installed directly from the Home Assistant Add-on Store or by adding this repository manually.

For complete installation and usage instructions, see the Add-on README.

Requirements

• Home Assistant OS or Home Assistant Supervised
• Supported architecture: amd64 or aarch64

Basic Setup

1. Install the add-on
2. Configure your upstream DNS servers and blocklists
3. Start the add-on
4. Point your router or devices to use your Home Assistant IP as the DNS server

Documentation

This repository contains documentation for different audiences:

Document	Audience	Contents
blocky/README.md	Users	Installation, configuration, usage, troubleshooting
blocky/DOCS.md	Advanced Users	Complete configuration reference, API documentation, performance tuning
CLAUDE.md	Developers	Architecture, development workflow, contribution guidelines

Repository Structure

.
├── CLAUDE.md                 # Developer documentation
├── blocky/                   # Main add-on directory (stable)
│   ├── config.yaml           # Add-on configuration schema
│   ├── DOCS.md               # Technical configuration reference
│   ├── README.md             # User-facing documentation
│   ├── Dockerfile            # Multi-architecture container build
│   ├── rootfs/               # Container filesystem overlay
│   │   ├── etc/cont-init.d/  # Initialization scripts
│   │   ├── etc/services.d/   # Service management scripts
│   │   └── usr/share/tempio/ # Configuration templates
│   └── translations/         # UI field descriptions
├── blocky-dev/               # Dev add-on (CI-managed, do not edit)
├── .github/workflows/        # CI/CD automation
├── scripts/                  # Build and release utilities
└── README.md                 # This file

Configuration

The add-on supports two configuration modes:

1. Standard Mode (Recommended) - Configure through the Home Assistant UI with guided options
2. Custom Config Mode - Use a custom Blocky YAML configuration file for advanced features

See the documentation for details.

Development Channel

A separate Blocky (Dev) addon is auto-deployed from the latest main branch on every push that changes blocky/. It lives in the blocky-dev/ directory.

Key differences from the stable addon:

• Local builds — HA builds the Docker image locally from the Dockerfile (no pre-built GHCR images)
• Auto-versioned — version is set to dev-<commit SHA> on each push
• CI-managed — do not edit blocky-dev/ manually; changes are overwritten by the Deploy Dev workflow
• Same ports — uses the same default ports (53, 4000) as stable; only one addon can run at a time

To use it, add this repository to your HA instance — both "Blocky" and "Blocky (Dev)" will appear in the add-on store.

Contributing

Contributions are welcome! Here's how you can help:

Reporting Issues

If you encounter problems or have feature requests, please open an issue with:

• A clear description of the issue
• Steps to reproduce (if applicable)
• Your Home Assistant version and architecture
• Relevant logs from the add-on

Development

For development setup and guidelines, see CLAUDE.md.

This project uses:

• Conventional Commits for commit messages
• Semantic Release for automated versioning and releases
• Multi-architecture Docker builds for broad platform support

Testing

Before submitting a PR:

1. Test your changes on your Home Assistant instance
2. Verify the add-on starts successfully
3. Check that DNS resolution works as expected
4. Ensure any configuration changes are properly documented

Credits

• Upstream Project: Blocky by @0xERR0R
• Home Assistant Community: For the excellent add-on ecosystem and tools
• Contributors: Everyone who has helped improve this add-on

License

This project is licensed under the MIT License - see the LICENSE file for details.

The upstream Blocky project is licensed under the Apache License 2.0.

Support

• Add-on Issues: GitHub Issues
• Blocky Documentation: Official Blocky Docs
• Home Assistant Community: Community Forum

---

Made with ❤️ for the Home Assistant community