Holeberry

English · 简体中文 · 日本語 · Website

Your Pi-hole, right in the menu bar.
A native and modern macOS menu bar app to monitor and control your Pi-hole® instances. No browser tab required.

#What is Holeberry?

Holeberry is a lightweight macOS menu bar app that puts your Pi-hole® at your fingertips. Check blocking status and query stats, disable blocking for a specific amount of time or indefinitely, unblock the domain in your current browser tab, and allowlist or unblock recently-blocked domains — all without opening the Pi-hole web interface.

It supports Pi-hole® v6 and v5 (not fully tested), multiple instances, and global keyboard shortcuts.

#Installation

1. Download the latest Holeberry-<version>.dmg from the Releases page.
2. Open the DMG and drag Holeberry into your Applications folder.

Holeberry is signed with a Developer ID and fully notarized by Apple.

#Requirements

• macOS 14 (Sonoma) or later — Holeberry is built with Swift 6 and takes advantage of modern macOS APIs.
• A Pi-hole® instance (v6 or v5) reachable from your Mac, on your local network or elsewhere.

#Features

#Multiple instances

Manage up to two Pi-hole® instances from one menu. Every action — blocking, unblocking, allowlist changes, and more — is applied to all instances at the same time.

This matters because there's no guarantee your Mac only uses the first DNS server. With Holeberry, every instance always stays in sync. Per-server status dots and aggregated stats are shown right in the menu.

#Status at a glance

The menu bar icon reflects your Pi-hole®'s health at all times, with per-instance status for multi-server setups. The menu also shows total queries and blocked domains across all your instances.

#Disable blocking with a timer

A quick way to disable blocking globally on all your Pi-hole® instances for a specific amount of time, or indefinitely. A timer pill in the menu bar shows the countdown, and blocking re-enables automatically when time's up.

#Unblock the browser tab you're on

Holeberry detects the current tab in WebKit (Safari, Orion), Chrome/Chromium, Gecko (Firefox, Zen, etc...) and unblocks that exact domain with one click — perfect when a page fails to load because Pi-hole blocked it. See the full list of supported browsers.

Unblocking a single domain beats a global disable: the page loads while the rest of your network stays protected. (Your smart TV would disagree — it sends so much traffic out into the world it would love a global unblock. Don't listen to it.) You can also add the domain to your allowlist.

#Gravity, right in your menu bar

Keep Pi-hole's blocklists fresh without opening the web admin interface: trigger a gravity update right from the menu bar, on all your servers simultaneously. It's available from the main menu or via a global keyboard shortcut you can set in Settings.

• Automatic gravity updates — update your Pi-hole's gravity on a schedule (every 6/12 hours, daily, weekly, or never).

#Glance the recently blocked domains

Browse the domains Pi-hole® blocked recently (from your Mac or all clients), and unblock or allowlist any of them straight from the menu.

#What's next?

Holeberry is a Pi-hole® app today, but the menu bar workflow doesn't have to stop there. If there's enough community interest, future versions could add:

• Support for other DNS providers — AdGuard Home and Technitium are natural candidates, for people who don't run Pi-hole®.
• Mixed setups — connect Pi-hole® and AdGuard Home (or any combination) side by side, with per-instance status, aggregated stats, and the same one-click controls across providers.

None of this is a commitment — it's a wishlist, and demand decides the order. If you'd like to see any of these, open an issue.

#FAQ

#Where are my Pi-hole credentials stored?

In the macOS Keychain — the same secure storage used by Mail, Safari, and your system. Holeberry never writes passwords to disk.

#Can I use a Pi-hole without a password?

Yes. Password-less instances (no web password set) are fully supported for both v5 and v6: just leave the password field empty when adding a connection. Holeberry stores no credential at all for such instances.

#What permissions does Holeberry need, and why?

• Local Network: required to connect to your Pi-hole instances.
• Automation (browser access): optional, only used when browser-tab unblocking is enabled. You can disable it anytime in Settings → General.

#Does Holeberry replace the Pi-hole web interface?

No, and it's not meant to. Holeberry is the remote control for the actions you take daily: status, toggling, and targeted unblocking. For deep configuration (adlists, DHCP), the web interface remains the tool — though you can now trigger gravity updates from the menu bar.

#Why doesn't my browser tab appear?

Browser-tab unblocking must be enabled in Settings → General, and Holeberry needs Automation permission for your browser (granted via System Settings on first use).

#Building from source

git clone https://github.com/pedrovieira/Holeberry.git
cd Holeberry
open Holeberry.xcodeproj

Select the Holeberry scheme and hit Run (⌘R).

Notes for contributors:

• The project uses XcodeGen — if you change project.yml, regenerate with xcodegen generate.
• The app target has pre-build scripts running SwiftLint and swift-format in strict mode; install them or the build will warn.
• Core logic lives in the HoleberryCore Swift package with its own test suite — cd Packages/HoleberryCore && swift test.

#Contributing

Bug reports and feature requests are welcome via issues. PRs should target the main branch, and the existing test suites should pass. AI-assisted contributions are welcome — if your PR was produced with AI assistance, please note it in the PR description and name the tool you used. Please open an issue first if you're planning something substantial — it saves both of us time.

#AI-assisted development

This project was primarily written by AI. I want to be upfront about that — but it was heavily guided by a human: me. AI generated and refined most of the code, but the architecture, the features, the scope, and the design decisions were directed and reviewed by me at every step. Treat the AI as an accelerator, not an author: the choices that make this codebase what it is are human choices. AI just made it faster to get there.

#Acknowledgements

• Sparkle — update framework
• KeyboardShortcuts — global shortcut recording
• Defaults — typed user defaults
• SymbolPicker — instance icon picker
• XcodeGen — project generation
• SwiftLint and swift-format — keeping the code honest

---

Pi-hole® is a registered trademark of Pi-hole LLC. Holeberry is an independent project and is not affiliated with Pi-hole LLC.