Installation & setup guide
Up and running in a couple of minutes. Pick your platform, install, and start your first scan. One license covers all your devices.
macOS notarized
- Download the .dmg and open it.
- Drag DeviceShelf into your Applications folder.
- Open it from Launchpad or Applications. It's notarized by Apple, so it just opens — no security warning.
Requirements: macOS 12 or newer (Apple Silicon & Intel). Live per-device bandwidth needs elevated rights — see live bandwidth. Everything else works out of the box.
Windows
- Download the installer (.exe) — x64 for Intel/AMD, or the ARM64 build for Snapdragon / Copilot+ PCs.
- Run it. Windows SmartScreen may warn that the publisher is unverified (the build is unsigned): click More info → Run anyway.
- Follow the installer and launch DeviceShelf.
For live bandwidth: install Npcap. Per-device bandwidth on Windows uses packet capture, which needs Npcap. The installer points you to it; you can also download Npcap and restart DeviceShelf. Scanning, ports, security report and everything else work without Npcap.
More: enabling live bandwidth.
Linux
DeviceShelf ships as an AppImage (runs anywhere, no install) and as native .deb / .rpm packages, for x86-64 and ARM64.
Installing the .deb? Use the terminal, not double-click — on Ubuntu 24.04 a double-clicked .deb opens in the App Center and can fail silently:
sudo apt install ./DeviceShelf-*.debFull Linux guide (AppImage, .rpm, capture rights): Install on Linux.
iPhone & Android
DeviceShelf for iPhone and iPad is on the App Store. Android ships as a direct APK you install yourself — there is no Google Play listing. Your license key works across desktop and mobile, so one purchase covers every device you own.
Run it 24/7 on a server included
A headless server edition for continuous, always-on monitoring runs in Docker, via .deb or as a Windows service. Point it at the networks you want watched around the clock. It is covered by your existing license: same key, no extra cost.
New in 1.5.3: the server includes a local MCP server — connect Claude, Cursor or any AI agent and ask about your network in plain language. Connection guide →
Install guide, alerts, token setup and MCP connection examples are in the server guide.
Home Assistant
The server edition publishes your devices to Home Assistant over MQTT. Home Assistant discovers them by itself, so there is nothing to install on its side beyond the MQTT integration and a broker — no add-on, no custom component.
- Make sure Home Assistant has the MQTT integration set up against your broker (the Mosquitto add-on works, so does any external broker).
- In the server dashboard open Settings → Integrations → Home Assistant, enter the broker address (
192.168.1.10:1883is enough), add a user and password if your broker needs them. - Tick Publish to Home Assistant and press Test connection. The entities show up within one scan interval.
Every exported device becomes one Home Assistant device with a presence sensor plus IP and latency, carrying vendor, model, type, OS and open ports as attributes. Alongside them sit network counters and an event entity firing on new devices, on devices going away and on newly opened ports, so an automation can react to an unknown device joining your network.
Favorites and infrastructure (gateway, routers, switches, access points, NAS, printers) are published automatically. Any other device can be added or excluded individually in its detail view.
Activate your license
- After purchase you receive a license key by email.
- In the app: Settings → License, paste the key, click Activate.
- On iPhone/Android, open the license email on the device and tap the activation button — it activates automatically.
No account, no online check — activation is offline. The same key re-activates on all your devices. More: activating DeviceShelf.
Permissions at a glance
| Feature | What it needs |
|---|---|
| Scanning, ports, security report, AI | Nothing — works everywhere, out of the box |
| Live per-device bandwidth | Windows: Npcap · macOS/Linux: elevated rights (sudo or BPF/setcap) |
| Passive DHCP fingerprinting | Elevated rights on macOS/Linux · not available on Windows |
Without these, the app still runs — only the respective feature stays inactive.
When something doesn't work
The scan finds nothing, or almost nothing
The scanner sees the network it is connected to. On a guest Wi-Fi, a VLAN or with a VPN active you scan that segment instead of your main one, which is the most common cause of a nearly empty list. On macOS, also check System Settings › Privacy & Security › Local Network: if DeviceShelf is not allowed there, a scan returns nothing at all. And give it half a minute — live hosts appear in seconds, names and identification follow.
Live bandwidth stays empty or greyed out
Per-device bandwidth uses packet capture, which needs extra rights: Npcap on Windows, sudo or BPF access on macOS/Linux. Everything else in the app works without it. The live bandwidth page walks through the setup per platform.
Windows warns about an unknown publisher
SmartScreen shows this for unsigned installers. Click More info → Run anyway. The download's SHA-256 checksum is published next to every release, so you can verify what you run.
The .deb does not install on Ubuntu
A double-clicked .deb opens Ubuntu's App Center, which can fail silently. Install it from the terminal instead: sudo apt install ./DeviceShelf-*.deb. Details on the Linux page.
The license does not activate
Paste the complete token from your purchase e-mail into Settings › License, with no line breaks. Verification runs offline, so no firewall can be in the way. If the token is rejected, reply to the purchase e-mail and we will sort it out.