https://github.com/robocopklaus/hassio-addon-blocky
Efficient DNS proxy and ad-blocker for Home Assistant, offering customizable filtering, advanced DNS settings, and modern protocol support for enhanced network security and performance.
https://github.com/robocopklaus/hassio-addon-blocky
blocky dns home-assistant home-assistant-addons
Last synced: 3 months ago
JSON representation
Efficient DNS proxy and ad-blocker for Home Assistant, offering customizable filtering, advanced DNS settings, and modern protocol support for enhanced network security and performance.
- Host: GitHub
- URL: https://github.com/robocopklaus/hassio-addon-blocky
- Owner: robocopklaus
- License: mit
- Created: 2023-08-08T12:25:46.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-02-22T17:37:33.000Z (4 months ago)
- Last Synced: 2026-02-22T19:44:06.795Z (4 months ago)
- Topics: blocky, dns, home-assistant, home-assistant-addons
- Language: Groovy
- Homepage:
- Size: 270 KB
- Stars: 11
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Blocky Home Assistant Add-On
A powerful DNS proxy and ad-blocker for your Home Assistant ecosystem.
[](https://opensource.org/licenses/MIT)
## About
This repository contains a Home Assistant add-on that packages [Blocky](https://github.com/0xERR0R/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](./blocky/README.md).
### 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](./blocky/README.md) | **Users** | Installation, configuration, usage, troubleshooting |
| [blocky/DOCS.md](./blocky/DOCS.md) | **Advanced Users** | Complete configuration reference, API documentation, performance tuning |
| [CLAUDE.md](./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](./blocky/README.md#configuration) 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-` 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](https://github.com/robocopklaus/hassio-addon-blocky/issues) 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](./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](https://github.com/0xERR0R/blocky) by [@0xERR0R](https://github.com/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](LICENSE) file for details.
The upstream Blocky project is licensed under the Apache License 2.0.
## Support
- **Add-on Issues**: [GitHub Issues](https://github.com/robocopklaus/hassio-addon-blocky/issues)
- **Blocky Documentation**: [Official Blocky Docs](https://0xerr0r.github.io/blocky/)
- **Home Assistant Community**: [Community Forum](https://community.home-assistant.io/)
---
Made with ❤️ for the Home Assistant community