/!\ Attention /!\ This is a WIP project. If you are interested to test it and give feedback, you are very welcome. Need feedbacks !
Visualize and monitor your homelab network as an interactive topology — inside Home Assistant.
This is the Home Assistant integration for Homelable, packaged as a custom repository for HACS.
Need the standalone (Docker / LXC / Web) version instead? See Pouzor/homelable.
- Interactive topology as a full Lovelace panel — pan, zoom, drag, group.
- Network discovery with nmap, with optional ARP / OS fingerprinting.
- Live status checks via ping, HTTP, TCP, or SSH.
- Rich modeling: 11 node types (router, switch, server, Proxmox, VM, LXC, NAS, IoT, access point, …) and 5 edge types (ethernet, Wi-Fi, IoT, VLAN, virtual).
- Zigbee2MQTT import: fetch your Zigbee mesh through HA's MQTT integration and add coordinator / routers / end devices to the canvas. No extra broker config — uses the broker HA already talks to.
- HACS → Integrations → ⋮ → Custom repositories
- Add
https://github.com/Pouzor/homelable-hacsas Integration. - Install Homelable.
- Restart Home Assistant.
- Settings → Devices & Services → Add Integration → search "Homelable".
- Copy
custom_components/homelable/into your HAconfig/custom_components/. - Restart Home Assistant.
- Add the integration from the UI as above.
- Home Assistant 2024.1 or newer.
nmapavailable on the host. (HAOS bundles it; Container / Core users may need to install it — see Scanner privileges.)
Setup is fully UI-driven (config flow). You'll be prompted for:
| Field | Default | Description |
|---|---|---|
| Network ranges | 192.168.1.0/24 |
Comma-separated CIDR blocks to scan |
| Scan interval | 60 min | How often to look for new devices |
| Status check interval | 60 s | How often to refresh node status |
All values can be changed later from the integration's Configure menu.
After setup, a Homelable entry appears in the sidebar. From there:
- Run a scan to discover devices on the configured ranges.
- Approve a discovered device to drop it on the canvas as a node.
- Connect nodes by drawing edges; pick the appropriate edge type.
- Save the canvas (explicit — no autosave).
Scan history, hidden devices, and scan configuration live in the side panel.
Full discovery features (ARP, OS detection, SYN scans) need raw socket access. If raw access is unavailable, the scanner falls back to TCP connect scans — still useful, but slower and without MAC addresses or OS fingerprints.
| Install type | Notes |
|---|---|
| HAOS / Supervised | Companion add-on with full privileges is planned. |
| Container | Run the HA container with CAP_NET_RAW, or setcap cap_net_raw+ep $(which nmap) inside the container. |
| Core | setcap cap_net_raw+ep $(which nmap) on the host. |
- HA entities per canvas node (
sensor.homelable_<id>,binary_sensor.homelable_<id>_online). - Device registry: one HA device per canvas node.
- Services:
homelable.scan_now,homelable.approve_device,homelable.refresh_status. - Events:
homelable_node_offline,homelable_node_online,homelable_device_discovered. - HACS default-listing submission once stable with real users.
See the issue tracker for the live list.
Issues and pull requests are welcome. Please:
- Open an issue first for non-trivial changes so we can align on scope.
- Keep PRs focused and include tests for behavior changes.
- Use Conventional Commits (
feat:,fix:,chore:,docs:,test:,refactor:).
MIT © Pouzor