Homelable: a self-hosted canvas that scans, documents and monitors a homelab

The gap Homelable targets: a diagram that goes stale the day after you draw it

Most homelab diagrams are drawn once, exported as PNG, and never touched again. Homelable's pitch is that the diagram is generated and then kept alive. The README describes it as a self-hosted infrastructure visualization solution with a network, Zigbee and Z-Wave scanning feature, so the starting point is a scan rather than a blank canvas. The audience is the person who already runs Proxmox, Zigbee2MQTT or Z-Wave JS and has accumulated devices faster than notes. Two details in the README tell you how the author thinks about scope. First, you can run the frontend alone and export a design as PNG, which means the drawing tool is usable without any of the backend. Second, there is a separate Home Assistant version distributed through HACS, so the full application is not aimed at people who want their lab inside Home Assistant's dashboard. The device inventory, the rack canvas and the markdown space are all first-class parts of the same product, not plugins.

Scan, import, draw, check: the four data paths into the canvas

The README names four ways content enters the tool. A one-click network scan identifies machines, devices and services on the local infrastructure. Proxmox VE, Zigbee and Z-Wave imports pull topology from systems you already run instead of rediscovering it. Manual placement covers everything the first three miss. Health checks then attach status to what is already on the canvas, using multiple methods: the README gives ping, TCP and a /health API as examples. The output side is a canvas that can be a network diagram or a rack, selectable from a canvas switcher via New Canvas then Kind then Rack. Rack canvases are physical: racks with a U height, 19-inch or 10-inch width, a numbering direction and colours, with gear mounted into a U range and part of a 12-column width grid so half-width and third-width machines can share a U. A drop snaps to the nearest free slot. Patch cables are drawn port to port and can cross racks. The README states that Import links derives patches from links already drawn on your diagrams, which is the clearest sign that the network view and the physical view are meant to stay in sync rather than being two unrelated drawings.

Device documents are generated once from scan facts, then left alone

The documentation model is the part worth reading closely. Every device gets a document generated once from what the scan actually found: identity, hardware, one section per service, network, operations, troubleshooting. The README is explicit that it is never rewritten behind you, and that saving is explicit everywhere. Slash inserts a freshly generated block (services, hardware, network, rack) from the device's current data, so regeneration is a deliberate action rather than a background job. Beside the generated documents sits a Library of pages you write yourself: runbooks, incidents, decisions, a network overview, started from a template or blank. Linking uses [[VLAN plan]] and [[device:nas-01]] syntax, and each document lists Linked from at the bottom. The tree can be re-pivoted by zone, subnet, type, rack, vendor or tag, and the README notes this costs nothing because it is grouped from data the app already holds. That is a coherent design: the tool refuses to silently overwrite your notes, and it refuses to make you re-file them when you change your mind about grouping. The cost is that a generated document drifts from reality the moment hardware changes, and nothing in the material suggests automatic reconciliation.

Getting it running: Docker images, a bare-metal script, or frontend only

The README points to INSTALLATION.md for the full matrix. Pre-built Docker images are published to GHCR. There is a Proxmox LXC path. Bare metal without Docker is covered by sudo bash scripts/install-baremetal.sh, which the README says installs a systemd unit plus nginx on a Debian or Ubuntu host. Building from source and a development setup are also listed. Configuration keys are not reproduced in the README, so anyone evaluating this should read INSTALLATION.md and FEATURES.md before committing, since the README states that every feature, with how to turn it on, is described in FEATURES.md. The release cadence visible in the material is tight: v3.3.5 on 2026-08-21, then v3.4.0 and v3.4.1 on 2026-09-07, with the last push to main on 2026-09-10. Three releases in under a month on a project at 3.x means you should expect to restart the container to pick up fixes, and you should pin a tag rather than track latest if the diagram is something you rely on. There is also an optional MCP server for AI assistant integration, which the README lists as a feature but does not document in the excerpt available here.

Where it stops: status display is not alerting

The healthcheck system gives a global overview of online and offline services. That is a dashboard, not an alerting pipeline. Nothing in the supplied material describes notification channels, escalation, alert suppression, on-call routing or historical uptime retention. If your actual problem is that a service died at 03:00 and nobody noticed, Homelable will show you the red node in the morning; it will not wake you. The Zigbee and Z-Wave imports have a similar boundary. They read topology from Zigbee2MQTT and Z-Wave JS, so the accuracy of the imported mesh depends on those systems being reachable and current, and a device that has dropped off the Zigbee network may still appear on the canvas until the next import. The network scan has the ordinary constraint of any scanner: it sees what is routable from wherever it runs, so a container on a bridge network with no route to a management VLAN will produce an inventory with holes. The README does not describe scan depth, credentials or how it handles devices that block ICMP. Treat the generated inventory as a first draft to correct, which is consistent with how the documentation model treats generated text.

Compared with NetBox plus a diagramming tool

The obvious alternative for people who want authoritative infrastructure records is NetBox, usually paired with draw.io or a diagramming tool for the picture. The difference in approach is the direction of data flow. NetBox is a source of truth you populate and maintain, with a data model and API designed for that; it does not scan your network for you, and it does not draw a canvas. Homelable inverts the priority: the scan and the import produce the inventory, the canvas is the primary interface, and the documentation is attached to the devices on it. That makes Homelable faster to start and weaker as a system of record. If you need IPAM with allocation tracking, change history on every field, or an API other tools consume, NetBox is the right shape and Homelable is not. If you need to look at your lab, see which boxes are up, and know which port on which patch panel feeds the switch, Homelable is closer to the job. The rack canvas with port-to-port patching is the feature with no direct equivalent in the NetBox plus draw.io pairing, because in that pairing the patch cable lives in a drawing that nothing validates.

Licence, maintenance cost and the Home Assistant fork

Homelable is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is a permissive licence and imposes no copyleft obligation on your own work. It is not legal advice; read LICENSE before redistributing a modified build. Maintenance cost has two parts. The application side is a container or a systemd unit plus nginx, and the install script is the documented path for the latter, so the operational surface is small. The data side is the real cost: every device you add by hand, every patch cable you draw, and every Library page you write is content that only exists inside Homelable. The README does not describe an export format for the canvas or the documentation, so before you invest an evening in drawing your rack, check whether you can get that data back out. The separate homelable-hacs repository means Home Assistant users have a fork to track as well, and the two will not necessarily move together. The MCP server is listed as optional, and the excerpt here does not say what it exposes or how it authenticates, which is the first thing to check if you intend to connect an assistant to it.

Editorial conclusion

Homelable fits a homelab owner who wants the diagram, the rack layout and the device notes in one place and is willing to run a Docker container or a Debian/Ubuntu host with the provided install script. It does not fit anyone who needs alert routing, long-term metrics or multi-user permissions; the README describes health checks and a read-only public canvas, not an alerting pipeline. Before adopting it, verify two things in your own environment: that the network scan can reach the subnets you care about from wherever the container runs, and that the Proxmox, Zigbee2MQTT and Z-Wave import paths match the versions you actually run, since those are the features that decide whether the inventory fills itself or you type it in by hand.

Official sources

1. License: MIT
2. Pouzor/homelable on GitHub
3. Project website
4. README
5. Releases