opensourceprojects.dev

A broadsheet for software that doesn't ask for your email

Self-hosted homelab docs that scan, monitor, and draw your network
GitHub RepoViews35

Project Description

View on GitHub

Homelable: Documentation That Actually Knows What's on Your Network

You've got a homelab. You've also got a wiki page somewhere that was accurate six months ago, a diagram that's missing three devices you added since, and no real idea which services are actually up right now. Sound familiar? Homelable is a self-hosted tool that tries to fix all of that in one place—scanning your network, documenting what it finds, and monitoring it live.

What It Does

Homelable is a self-hosted infrastructure visualization and documentation solution. The core idea is that your homelab docs shouldn't live in a separate wiki that drifts out of sync with reality. Instead, Homelable scans your local network (plus Zigbee and Z-Wave devices) to identify the machines, devices, and services you've got running, then uses that to build out your documentation for you.

On top of the diagram side, it includes a healthcheck system that supports multiple probe methods—ping/TCP checks, /health API endpoints, and so on—so you get a global overview of what's online and what's offline. Every device gets its own document, written automatically from what the scan found and editable from there. There's also a Library for pages you write yourself: runbooks, incident notes, a network overview. The visualization side supports pre-built design styles, per-device customization, floor plans, and rack canvases with port-level detail. It's built in TypeScript, and if you only care about the design side, you can run just the frontend and export your diagram as a PNG.

Why It's Cool

  • The docs write themselves—at first. The most interesting decision here is that scanning isn't just for inventory. The scan output becomes the starting point for each device's document. You're not staring at a blank page for every switch and container; you're editing something that already reflects what's actually on the network.

  • It pulls from the things you already run. Proxmox VE import, Zigbee2MQTT import, Z-Wave import—these are the sources of truth in a lot of homelabs, and pulling from them beats typing device names by hand.

  • Monitoring lives next to the map. Healthchecks through ping/TCP and /health endpoints mean the diagram isn't just a pretty picture. You can see what's down without bouncing to a separate monitoring stack.

  • There's a read-only public view. The Live View feature lets you expose a read-only canvas—useful if you want to share your setup without handing out write access.

  • It plays nice with AI tooling. There's an optional MCP server and a REST API, so you can wire Homelable into other things rather than treating it as a dead-end app.

  • Home Assistant users get a dedicated path. If you're running HA, there's a separate Homelable HACS version, which suggests the author actually uses this stuff rather than shipping a one-off.

The honest caveat: this is a young project (the README is still partially truncated, and it's clearly evolving), so expect rough edges. But the scope is ambitious in a useful way—it's not just a diagramming tool with a scanner bolted on.

How to Try It

The project is at github.com/Pouzor/homelable, and it's MIT licensed with Docker-based builds, so the usual path applies:

  1. Head to the releases page and grab the latest version.
  2. Check the Installation section of the README for the Docker setup—the CI workflow suggests container images are the primary distribution method.
  3. Run a network scan to populate your inventory, then import from Proxmox, Zigbee2MQTT, or Z-Wave if you use them.
  4. Set up healthchecks on the services you care about, and start filling in the Library with your runbooks.

If you're a Home Assistant user, skip the manual setup and use the Homelable HACS version instead. And if you just want the visuals, you can run the frontend alone and export a PNG.

Final Thoughts

Homelable is aimed squarely at people who run a real homelab and are tired of their documentation being a lie. The combination of scanning, auto-generated device docs, and live healthchecks is a sensible answer to a problem most of us solve badly. It won't replace a full monitoring stack or a proper CMDB, and it's early enough that you should expect some friction—but if you want your network diagram to reflect what's actually plugged in, this is worth a look.


Follow @githubprojects for more developer tools and open source projects.

Back to Projects
Project ID: homelableLast updated: November 18, 2026 at 06:14 AM