If you already use Home Assistant as your homelab control center, the SMART Sniffer Home Assistant Setup is the fastest way to get drive health alerts without running a separate dashboard. 🎯
The idea is simple: a lightweight agent runs on each machine you want to monitor, reads SMART data via smartctl, and serves it over HTTP. The HA integration polls each agent and turns every drive into its own HA device — with sensors, diagnostics, and automatic persistent notifications. No automations, no blueprints, no extra UI to maintain.
If you’ve read my post on Scrutiny, you know that tool gives you a standalone dashboard with long-term history graphs. SMART Sniffer skips the separate UI entirely — drive health lives directly inside HA. And unlike Scrutiny, agents auto-discover over mDNS, so new machines appear in HA without manual configuration.
Prerequisites 🛠️
A successful SMART Sniffer Home Assistant Setup requires:
- Home Assistant (HAOS, Supervised, or Core) with HACS installed
- SSH or console access with
sudoon each Linux machine you want to monitor - Network connectivity between your HA host and each agent machine
Step 1 — Install the Integration via HACS 🏠
Start here. The integration is what connects everything to Home Assistant — install it first before touching any agents.
- Open HACS → three-dot menu (⋮) → Custom repositories
- Paste
https://github.com/DAB-LABS/smart-sniffer, category: Integration - Search for SMART Sniffer and click Download
- Restart Home Assistant — required before the integration appears in the add flow
The integration is the core of the SMART Sniffer Home Assistant Setup — without it, the agents have nowhere to report to.
Step 2 — Monitor Your Home Assistant Machine 🖥️
This is the part that’s usually left out of any SMART Sniffer Home Assistant Setup guide — what about the drive in the machine that runs Home Assistant?
The answer depends on how you installed HA.
If you’re running Home Assistant OS (HAOS)
HAOS is a locked-down system — you can’t just SSH in and run a shell script. For this, the team at DAB-LABS published a dedicated HAOS App (what used to be called an Add-on): a native HA App that starts on boot, reads your drive’s SMART data, and exposes it to the integration — all without leaving the HAOS boundary.
Install it through the Add-on store:
- Go to Settings → Add-ons → Add-on Store
- Click the three-dot menu (⋮) → Repositories
- Paste
https://github.com/DAB-LABS/smart-sniffer-appand click Add - Find SMART Sniffer App in the store and click Install
- After install, go to the Info tab → click Start
- On the same Info tab — enable Start on boot and Watchdog
⚠️ Disable Protection mode: By default HAOS blocks hardware access for Apps. Without this, the agent detects the drive but can’t read it. On the Info tab, find the Protection mode toggle → turn it off → restart the App. After restart, the logs should show Drive access: OK instead of a warning.
After start, the App advertises itself over mDNS, so the integration will discover it — no manual IP entry needed.
If you’re running HA Supervised or HA in Docker
In this case, HA runs on top of a regular Linux host you have full access to. Just SSH into that host and install the agent the same way you would on any other Linux machine (see Step 3 below). The agent will pick up the host’s drives and report them to HA alongside everything else.
Step 3 — Install the Agent on Other Linux Machines 🐧
For every other Linux machine — a Proxmox host, NAS running OpenMediaVault, any Debian/Ubuntu box — the SMART Sniffer Home Assistant Setup agent installs with one command.
⚠️ If you’re on Proxmox: SSH directly into the bare-metal host, not into an LXC or VM. The agent needs direct access to physical block devices to read SMART data. Running it inside a container won’t see the host’s drives.
# If you're running as root (e.g. Proxmox):
curl -sSL https://raw.githubusercontent.com/DAB-LABS/smart-sniffer/main/install.sh | bash
# If you're running as a regular user:
curl -sSL https://raw.githubusercontent.com/DAB-LABS/smart-sniffer/main/install.sh | sudo bash⚠️ This is a pipe-to-bash install running as root. Review the install.sh source before running if that matters to you. Always a reasonable habit.
The installer is interactive — here’s what it asks step by step.
Port and auth:
Port [9099]:
Bearer token for API auth (leave blank to disable):
Scan interval (e.g. 60s, 30m, 24h) [60s]:Press Enter to accept the default port 9099. Leave the token blank unless you want auth. For scan interval — 60s is fine for SSDs, 30m makes more sense for HDD-heavy setups where you don’t want constant polling.
Disk usage monitoring — the installer lists all detected mountpoints and asks which ones to track:
Monitor (1,2..5 / all / none) [all]:Pick only the mountpoints that matter. Skip things like /boot/efi — it’s tiny and never fills up. If you have a ZFS pool with child datasets mounted separately, tracking the parent pool mount is enough — the children live in the same space.
mDNS network interface — Home Assistant uses this to auto-discover the agent:
Advertise on (1-2 / all) [all]:Pick your LAN interface only — skip lo (loopback, 127.0.0.1). HA can’t reach the agent over loopback. Select the interface with your actual LAN IP. If the machine runs Docker, you’ll see a lot of br-xxxxxxxx Docker bridge interfaces in the list — skip all of those too, pick only the real physical interface.
Standby-aware polling — shown only if HDDs are detected:
Enable standby-aware polling? [Y/n]:Answer Y if you have spinning drives. Without it, the agent wakes up sleeping drives every scan cycle, which defeats the point of spindown. With it enabled, sleeping drives are skipped and served from cache.
When prompted, optionally set an auth token — if you do, write it down. You’ll need it when connecting the agent to HA.
After installation, confirm the agent is running — this is your last check before wiring everything into the SMART Sniffer Home Assistant Setup:
# Check service status
systemctl status smartha-agent
# Quick endpoint test — should return JSON with "status":"ok"
curl http://localhost:9099/api/health
# With auth token:
curl -H "Authorization: Bearer your-token" http://localhost:9099/api/healthStep 4 — Connect the Agent to Home Assistant 🔌
Thanks to mDNS auto-discovery, the SMART Sniffer Home Assistant Setup can find agents automatically. Check Settings → Devices & Services — if you see a SMART Sniffer discovery notification, just confirm it.
If auto-discovery doesn’t trigger, add it manually:
Settings → Devices & Services → Add Integration → SMART Sniffer
The integration will ask for:
- Host — IP address of the machine running the agent (e.g.
192.168.1.10). For the HAOS App specifically, use the internal hostname shown in the App logs — look for the lineIntegration host:and copy the value before the colon (e.g.0449a086-smart-sniffer-agent) - Port — port the agent is listening on (default:
9099) - Bearer Token (optional) — the auth token you set during install; leave blank if you skipped auth
- Polling Interval (seconds) — how often HA polls for updated SMART data (default:
60)
After submitting, drives from that machine appear as individual HA devices. Repeat for each machine. 🎉
Step 5 — Understanding Drive Sensors 🔍
Each drive gets its own HA device with a set of entities. The most important one is Attention Needed — this is the SMART Sniffer Home Assistant Setup’s proactive health signal:
- NO — all monitored indicators are clear. Nothing to do.
- MAYBE — early degradation signals detected. Monitor closely, plan for replacement.
- YES — data integrity at risk. Back up immediately.
- UNSUPPORTED — drive doesn’t expose usable SMART data. Most common with USB enclosures — hardware limitation, not a config problem.
When a drive’s state changes, HA fires a persistent notification automatically — no automations needed. It escalates as conditions worsen and dismisses when they improve.
Other useful entities per drive:
- Reallocated Sector Count — bad sectors remapped to spares. Any non-zero value deserves attention.
- Current Pending Sector Count — sectors waiting to be reallocated. Watch this closely.
- Reported Uncorrectable Errors — unrecoverable read/write failures.
- Temperature and Power-On Hours — useful context when reading the other stats.
If you also enabled disk usage monitoring during the agent install, the SMART Sniffer Home Assistant Setup will create a separate “Disk Usage ({hostname})” device with percentage-used sensors per mountpoint. Handy for watching your NAS fill up. 📊
Verifying the Full Setup ✅
Go to Settings → Devices & Services → SMART Sniffer and click any drive device. If temperature and power-on hours are populated, the SMART Sniffer Home Assistant Setup is working correctly.
Troubleshooting 🔧
“Unable to connect to the SMART Sniffer agent”
HA discovered the agent via mDNS but can’t reach it — the most common issue in any SMART Sniffer Home Assistant Setup and almost always a firewall problem.
Step 1 — confirm the agent is actually running on the remote machine:
systemctl status smartha-agent
curl http://localhost:9099/api/health
If the local curl returns JSON with "status":"ok" — the agent is fine, the problem is network.
Step 2 — test connectivity from the HA host:
curl http://<agent-ip>:9099/api/healthIf this hangs or times out — the port is being blocked between HA and the agent machine.
Step 3 — open port 9099 in the firewall. This is where you need to slow down and figure out which firewall is actually running on the host. Don’t just pick the first UI you find. Read on.
⚠️ A trap I fell into myself
An earlier draft of this SMART Sniffer Home Assistant Setup guide pointed you straight at OMV’s Network → Firewall page to add the rule. I followed my own advice on my NAS — and lost SSH access for an evening. Here’s what actually goes wrong under the hood, so you can avoid the same trap.
My OMV box already had ufw configured with rules for SSH (22), HTTP/HTTPS (80/443), SMB (139/445), and a bunch of Docker-proxied services. UFW was working fine. Then I needed to open 9099 for HA, opened the OMV web UI, added the rule there, hit Apply — and my SSH session froze. New SSH connections timed out. Web services on Docker ports became unreachable too.
Why it happened. OMV ships with its own native firewall that’s completely separate from ufw. Both manipulate iptables. When you add a rule via the OMV UI, OMV regenerates its firewall script and runs something roughly like this:
iptables -F INPUT # flush EVERY rule from INPUT
iptables -P INPUT DROP # default: drop everything
iptables -A INPUT -p tcp --dport 9099 -j ACCEPT # only what you addedNotice what it doesn’t do: it doesn’t preserve ufw‘s rules. The flush wipes the jumps from INPUT into ufw‘s chains. UFW’s chains still exist but nothing routes into them anymore. Result: INPUT policy = DROP, only port 9099 explicitly allowed — SSH dead, everything else dead.
To make it worse, even after I removed the OMV rule, UFW didn’t recover on its own. UFW saw its chains were still present and skipped re-adding the INPUT jumps. SSH stayed dead until I did a full ufw --force reset.
This isn’t OMV-specific. Any setup where two firewall managers think they own the INPUT chain will eventually do this to you. Pick one firewall manager and stick with it.
Doing it properly
On OpenMediaVault — do NOT use Network → Firewall → Rules in the UI if you have ufw installed. Add the rule via ufw instead:
sudo ufw allow 9099/tcp comment "smartha-agent for HA"
sudo ufw status numberedIf you’ve never used ufw on this box and want OMV’s UI firewall to be the single source of truth, that’s also valid — just make sure you add all your existing rules there (SSH 22, HTTP/HTTPS 80/443, SMB 139/445, etc.) before clicking Apply, otherwise you’ll lock yourself out.
On other Linux machines, the tool depends on the distro:
- Debian/Ubuntu with ufw:
sudo ufw allow 9099/tcp - RHEL/Fedora with firewalld:
sudo firewall-cmd --permanent --add-port=9099/tcp && sudo firewall-cmd --reload - Plain nftables:
sudo nft add rule inet filter input tcp dport 9099 accept - Plain iptables:
sudo iptables -A INPUT -p tcp --dport 9099 -j ACCEPT(and persist viaiptables-save)
The principle is the same — allow inbound TCP on port 9099. The trap is using two of these tools at once.
How to recover if you already broke it
If you added a rule via the OMV UI while ufw was active and now SSH is dead:
1. Get a console session — physical keyboard and monitor, IPMI, or your hypervisor’s console. SSH probably won’t work.
2. Disable both firewalls cleanly:
sudo systemctl disable --now openmediavault-firewall.service
sudo ufw --force reset3. Verify INPUT is clean:
sudo iptables -L INPUT -n -vShould show only the policy line with no orphan rules.
4. Re-add your rules through ufw only:
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp comment "SSH"
sudo ufw allow 80/tcp comment "HTTP"
sudo ufw allow 443/tcp comment "HTTPS"
sudo ufw allow 9099/tcp comment "smartha-agent for HA"
sudo ufw enable5. Sanity check — confirm UFW wired itself into INPUT:
sudo iptables -L INPUT -n -v --line-numbersYou should see ufw-* jumps in the chain. If INPUT is empty with only policy DROP, UFW didn’t hook in. Delete the orphan chains and re-enable:
sudo ufw disable
for c in ufw-before-input ufw-after-input ufw-user-input \
ufw-before-logging-input ufw-after-logging-input \
ufw-reject-input ufw-track-input; do
sudo iptables -F $c 2>/dev/null
sudo iptables -X $c 2>/dev/null
done
sudo ufw enableAfter this, curl http://<agent-ip>:9099/api/health should respond and HA should pick up the agent within seconds.
HAOS App — Drive access: OK not showing
Make sure Protection mode is disabled on the Info tab of the App. Without this, the App can see the drive but can’t read its SMART data.
HAOS App not discovered automatically
Check Settings → System → Logs and filter for smart_sniffer. Also confirm the App is started and the Info tab shows it as running. If mDNS still doesn’t work, add it manually via Add Integration using the internal hostname from the App logs (Integration host: line).
Tweaking the Agent Config ⚙️
The agent config lives at /etc/smartha-agent/config.yaml. Edit it if you need to change port, auth token, or scan interval after completing the SMART Sniffer Home Assistant Setup:
port: 9099
token: "your-secret-token" # optional — omit entirely to disable auth
scan_interval: 60sAfter any config change:
# Restart to apply changes
systemctl restart smartha-agentDrive health is one of those things that’s invisible right up until it’s catastrophic. 💪
If you’re running a NAS, also check out how to disable disk sleep and spindown on Linux and OpenMediaVault — excessive spindown cycles quietly shorten drive lifespan over time.
And if your Proxmox host is freshly installed, the Proxmox VE post-install script guide covers the first-day optimizations worth running before deploying any agents.
Set up the SMART Sniffer Home Assistant Setup once, and your drives will tell you when they’re in trouble — long before they fail. 🐾