Homelable‑hacs brings a visual network‑topology panel into Home Assistant, letting users scan their homelab, drag‑and‑drop devices, and watch live status checks without leaving the HA UI. Packaged as a custom HACS integration, it ties directly into Home Assistant 2024.1+ and relies on nmap for discovery, while also pulling Zigbee2MQTT topology data from HA’s own MQTT broker.

Architecture

The integration lives under custom_components/homelable and is written in TypeScript. Its core responsibilities are three‑fold:

  1. Discovery engine – a thin wrapper around nmap that can run ARP, OS fingerprinting, and SYN scans when raw‑socket privileges are available. If raw access is missing, the scanner gracefully degrades to TCP connect scans.
  2. Data model – a canvas‑style graph consisting of 11 predefined node types (router, switch, server, Proxmox, VM, LXC, NAS, IoT, access point, etc.) and five edge categories (ethernet, Wi‑Fi, IoT, VLAN, virtual). The model is kept in Home Assistant’s storage and can be exported or edited via the UI.
  3. UI layer – a Lovelace panel that renders the graph with pan, zoom, drag, and grouping capabilities. The panel also exposes controls for scanning, approving devices, drawing connections, and saving the canvas.

Optional Zigbee2MQTT import works by reading the Zigbee mesh from HA’s MQTT integration; no separate broker configuration is required. The integration does not ship any background services beyond the occasional nmap invocation triggered by the configured scan interval.

What you can do with it

  • Run periodic scans: define one or more CIDR blocks (default 192.168.1.0/24) and let nmap discover hosts on the specified schedule (default every 60 minutes).
  • Approve devices: newly discovered hosts appear in a side panel; users can approve them, which creates a node on the canvas.
  • Live status checks: each node can be probed via ping, HTTP, TCP, or SSH at a configurable interval (default 60 seconds). The result surfaces as a binary sensor (binary_sensor.homelable_<id>_online).
  • Edit topology manually: draw edges between nodes and select the appropriate edge type (e.g., VLAN or virtual).
  • Import Zigbee mesh: automatically add Zigbee coordinators, routers, and end‑devices to the graph without extra setup.

The roadmap hints at deeper HA integration: exposing each canvas node as a regular HA entity, registering devices in the HA device registry, and adding service calls such as homelable.scan_now or homelable.refresh_status. Event streams (homelable_node_online, homelable_device_discovered, etc.) are also planned.

Constraints and gotchas

  • Home Assistant version: requires 2024.1 or newer; older releases lack the necessary integration hooks.
  • nmap dependency: the host must provide the nmap binary. HAOS includes it, but users running Home Assistant in Docker or Core may need to install it manually and grant raw‑socket capabilities (CAP_NET_RAW) for full‑feature scans. Without those privileges, discovery falls back to slower TCP connect scans and loses MAC/OS data.
  • Platform nuances: on HAOS / Supervised a future companion add‑on is expected to handle privileges automatically. In container deployments, the container must be started with CAP_NET_RAW or the binary must be wrapped with setcap. Core installations need the same setcap applied on the host.
  • Stability: the README marks the project as a work‑in‑progress; many roadmap items (HA entities per node, service calls, events) are still pending. Users should expect occasional breaking changes and limited community support at this stage.
  • Persistence: canvas changes are saved only when the user explicitly clicks “Save”; there is no autosave, so accidental closures can discard work.

Getting started

The quickest way to add Homelable is through HACS: add the repository URL (https://github.com/Pouzor/homelable-hacs) as a custom integration, install it, restart Home Assistant, and then add the integration via the UI. The README contains the exact steps and also describes a manual copy‑paste method for those who prefer it. Configuration is driven entirely by the UI, where you set network ranges, scan intervals, and status‑check intervals.

If you need a standalone version that runs in Docker, LXC, or as a web service, the original Homelable project (Pouzor/homelable) is the place to look.

Homelable‑hacs is a niche tool aimed at homelab enthusiasts who already run Home Assistant and want a visual representation of their network without managing a separate topology app. For users whose primary need is simple device monitoring, native HA integrations (e.g., ping sensors, the built‑in network integration) may be lighter. When a graphical map of routers, switches, VMs, and Zigbee devices is valuable, this integration fills a gap that most other Home Assistant add‑ons ignore. The source is on GitHub.