About
Homelable is a self-hosted infrastructure visualization solution. It provides a network/zigbee/zwave scanning feature to accelerate the identification of machines, devices and services deployed on your local infrastructure.
Homelable also offers a healthcheck system through multiple methods (ping/TCP, /health API, etc.) to get a global overview of online/offline services.
Every device also gets a document — written for you from what the scan found, and yours to maintain from there — next to a Library of pages you write yourself: runbooks, incidents, a network overview. Your homelab stops being documented in a wiki somewhere else.
You can also select some pre-built design styles, or personalize each device in your diagram.
If you just like the design, you can only run the frontend and export your design as PNG.
If you are running Homeassistant, check the Homelable HA version (via HACS)
Screenshots
Features
From one-click network scans and Proxmox / Zigbee / Z-Wave imports to live status monitoring, floor plans, rack canvases with port-to-port patching, a markdown documentation space for the whole lab, multi-canvas layouts and an MCP server for AI assistants — Homelable maps, documents and watches your whole homelab.
Every feature, with how to turn it on and use it, is described in FEATURES.md.
Installation
Docker (from the pre-built GHCR images), Proxmox LXC, bare metal without Docker (sudo bash scripts/install-baremetal.sh — systemd unit plus nginx on a Debian/Ubuntu host), build from source, configuration, and development setup are all covered in INSTALLATION.md.
☁️ One-Click Cloud Deploy
Rack Canvas
Next to the network diagram, Homelable draws the physical side of your lab: racks, the gear mounted in them, and the patch cables between their ports. It is a canvas kind of its own — create it from the canvas switcher, New Canvas → Kind → Rack.
Usage
- Add Rack in the header drops a rack; double-click its frame to set U height, 19"/10" width, numbering direction and colours
- + Device in the sidebar mounts something — an entry from your Device Inventory, a new device (which joins the inventory), or an accessory (blank, shelf, cable manager)
- Pick a faceplate from the visual catalog: servers, switches, routers, patch panels, UPS and PDUs, desktop NAS towers, shelves and blanks
- Click Patch, then drag from one port to another to cable them — across racks if you need to. Click a cable and press Delete to unplug it
- Save Rack when you're happy; nothing is written behind your back
Gear sits in a U range and part of a 12-column width grid, so half- and third-width machines share a U; a drop snaps to the nearest free slot. A mount can follow the status check of its matching diagram node, and Import links derives patches from the links already drawn on your diagrams.
Full documentation: docs/rack-canvas.md
Documentation
Homelable keeps its own markdown documentation space, so the lab is described where it is drawn. Sidebar → Documentation.
Every device has a document, generated once from what the scan actually found — identity, hardware, one section per service, network, operations, troubleshooting — and never rewritten behind you. Beside it, a Library of pages you write: runbooks, incidents, decisions, a network overview, from a template or blank.
Usage
- Pick a device in the tree — one with no document yet gets one written from its facts. Re-pivot the tree by zone, subnet, type, rack, vendor, tag… at no cost; it is grouped from data the app already holds
- Write markdown, save explicitly — nothing is ever saved behind your back.
/ inserts a freshly generated block (services, hardware, network, rack) from the device's current data
- Link things:
[[VLAN plan]], [[device:nas-01]]. Each document lists Linked from at the bottom, so you can see what points at it
- History: up to 50 versions per document. Read one, diff it against the current body, restore it — what it replaces is kept too
- Search the whole space, tag documents, and set
review_every: 6m on the ones that rot; a document past its interval is badged as due
A device that changes after its document was written raises a device data changed banner, and Regenerate rebuilds the document from scratch when you want that. Old per-device Notes migrate into documents from a banner, non-destructively.
Full mode only — documents need the backend to store, index and search them.
Full documentation: docs/documentation.md
Documentation View (read-only public documentation)
Documentation View shares your documentation space — the tree, the pages and their
version history — with anyone on your network, no login required. It is disabled by
default, and uses its own key: enabling Live View does not enable this.
Activation
Add DOCS_VIEW_KEY to your .env:
DOCS_VIEW_KEY=your-secret-key
Generate one with python3 -c "import secrets; print(secrets.token_urlsafe(32))", then
restart the backend:
docker compose restart backend
Usage
Use this URL to read your documentation:
http://<your-homelab-ip>/documentation?key=your-secret-key
The page shows the document tree, the filter box and any page you pick, plus its earlier
versions. Nothing can be written: no editing, no restoring, no deleting. Your device
inventory and your canvases are not reachable through it.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
