homelable
Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
What is it?
What it is
Homelable is a self-hosted infrastructure visualization and monitoring tool for homelabs, enabling network scanning, device imports (Zigbee, Z-Wave, Proxmox), live status tracking, and customizable diagrams.
Why it exists
To provide open-source, self-hosted visibility into homelab ecosystems, reducing reliance on external services and enabling granular control over infrastructure monitoring and management.
Who should use it
Teams building with TypeScript who want an open-source, self-hosted option.
Who should avoid it
Teams that need a fully managed SaaS with enterprise SLAs out of the box.
How it works
A quick walkthrough in plain English
How homelable works
Step 1 of 3
You interact with it
Open homelable, send a request, or connect it to your stack.
Features
Advantages
- Automated device discovery through network scanning
- Visualizes complex IoT topologies (Zigbee/Z-Wave)
- Reduces manual documentation effort with Proxmox API integration
- Real-time health monitoring of services
- AI-ready via Model Context Protocol (MCP)
- Customizable node designs and styles
Disadvantages
- Network scanning may require root/sudo privileges for certain scan types
- Requires manual approval for discovered devices to be added to the canvas
- Requires additional configuration/setup for advanced features like MCP or Live View
Installation
docker
Docker, Proxmox LXC, build from source, configuration, and development setup are all covered in INSTALLATION.md
native
Proxmox LXC / bare-metal (no Docker): create the LXC via community-scripts/ProxmoxVE (or any Debian/Ubuntu LXC), then inside it run `sudo bash scripts/lxc-mcp-install.sh`.
compose
docker compose restart backend
FAQ
How do I run a network scan and see the discovered devices?
Open the Homelable UI, click **Scan Network** in the sidebar. The Scan History tab opens and refreshes every 3 seconds until the scan finishes. Discovered hosts appear in the **Pending Devices** queue where you can approve, hide, or ignore them before adding them to the canvas.
How can I import my Zigbee network from Zigbee2MQTT?
In the sidebar click **Zigbee Import**. Enter your MQTT broker host, port (default 1883), optional credentials, and base topic (default zigbee2mqtt). Click **Test Connection** then **Fetch Devices**. Select the devices you want from the grouped list and click **Add N to Canvas** – devices are placed in a grid with proper hierarchy and LQI stored as a property.
What steps are required to enable the read‑only Live View?
Add a `LIVEVIEW_KEY` to your `.env` file, e.g. `LIVEVIEW_KEY=your-secret-key`, then restart the backend (`docker compose restart backend`). The public URL is `http://<your-homelab-ip>/view?key=your-secret-key`. Anyone on the network can view the canvas in pan/zoom mode without logging in.
How do I set up the MCP server for AI integration?
Add `MCP_API_KEY` and `MCP_SERVICE_KEY` to your `.env` (generate with `python3 -c "import secrets; print(secrets.token_hex(32))"`). Then run `docker compose up -d mcp`. The server listens on port 8001. Configure your AI client (e.g. Claude Code) to use this URL with the header `X-API-Key: <MCP_API_KEY>`.
How can I import my Proxmox VE inventory into Homelable?
In the sidebar click **Proxmox Import**. Provide the host, port (default 8006), and a Proxmox API token with the `PVEAuditor` role. Click **Test Connection**, choose a target (Pending or Canvas), then **Import to Pending** or **Fetch Inventory**. Select the hosts, VMs, or LXC containers you want and add them to the canvas. Auto‑sync can be enabled from Settings once the token is configured.
Featured in Videos
YouTube tutorials and walkthroughs for homelable
Alternatives
Similar projects ranked by category, topics, and text overlap.
