Homelable

A self-hosted, open-source tool to visually map, document and monitor your homelab infrastructure.

Interactive network canvas where each node is a physical machine, VM, LXC container, switch, or device. Nodes show live status, IPs, hostnames, and running services. Edges represent network links.

---

Features

• Interactive canvas — drag, zoom, pan, snap-to-grid (React Flow)
• 11 node types — ISP, router, switch, server, Proxmox, VM, LXC, NAS, IoT, AP, generic
• Proxmox nested nodes — VM/LXC rendered inside a resizable Proxmox group container
• 5 edge types — ethernet, Wi-Fi, IoT, VLAN (color-coded), virtual
• Live status — per-node checks via ping / HTTP / HTTPS / SSH / TCP / Prometheus
• Network scanner — nmap-based discovery, approve/hide/ignore new devices
• Auto-layout — one-click Dagre hierarchical arrangement
• Export — download canvas as PNG
• Dark theme — neon accent colors, JetBrains Mono for technical values
• Self-contained — SQLite database, single config file, no cloud dependency

---

Quick Start — Docker

git clone https://github.com/you/homelable.git
cd homelable

docker compose up -d

Open http://localhost:3000 — login with admin / admin.

Change the password before exposing to a network: edit backend/config.yml and replace password_hash with a new bcrypt hash.

Generate a hash: docker compose exec backend python -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('yourpassword'))"

---

Quick Start — Development

Backend (Python 3.13):

cd backend
python3.13 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # edit SECRET_KEY
uvicorn app.main:app --reload --port 8000

Frontend:

cd frontend
npm install
npm run dev   # http://localhost:5173

Default login: admin / admin

---

Proxmox LXC Install

Run inside a Debian/Ubuntu LXC container:

bash <(curl -fsSL https://raw.githubusercontent.com/you/homelable/main/scripts/lxc-install.sh)

This installs the backend as a systemd service and serves the frontend via nginx.

---

Configuration

backend/config.yml:

auth:
  username: admin
  password_hash: "$2b$12$..."   # bcrypt hash

scanner:
  ranges:
    - "192.168.1.0/24"          # CIDR ranges to scan

status_checker:
  interval_seconds: 60          # how often to check node status

All settings are also editable in-app via the Scan Network button.

---

Network Scanner

The scanner runs nmap -sV --open on your configured CIDR ranges and populates a Pending Devices queue. From the sidebar you can then approve (adds a node to the canvas), hide, or ignore each discovered device.

Triggering a scan

Click Scan Network in the sidebar. The Scan History tab opens automatically and refreshes every 3 seconds until the scan completes. Errors are shown inline and as a toast notification.

macOS / root privileges

Some nmap scan types (SYN scan, OS detection) require root. If the scan fails with a permissions error, run it manually with sudo using the included script:

cd backend
sudo python ../scripts/run_scan.py 192.168.1.0/24

# Multiple ranges:
sudo python ../scripts/run_scan.py 192.168.1.0/24 10.0.0.0/24

Results are written directly to the database and appear as Pending Devices in the UI without restarting the backend.

On Linux the backend process itself can be given the NET_RAW capability instead of running as root:

sudo setcap cap_net_raw+ep $(which nmap)

---

Proxmox Nested Nodes

Proxmox nodes render as a resizable group container. VM and LXC nodes can be placed inside:

1. Add a Proxmox VE node to the canvas
2. Add a VM or LXC node — select the Proxmox node in the Parent Proxmox dropdown
3. The child node appears inside the group and moves with it
4. Select the Proxmox node to reveal resize handles (drag corners to expand)

---

Node Check Methods

Method	Description
ping	ICMP ping
http	GET request, success if status < 500
https	GET with TLS verify
tcp	TCP connect (target: host:port)
ssh	TCP connect to port 22
prometheus	GET /metrics
health	GET /health

---

Stack

Layer	Tech
Frontend	React 18, TypeScript, Vite, React Flow v12, Zustand, Tailwind CSS, Shadcn/ui
Backend	FastAPI, SQLAlchemy async, SQLite, APScheduler, python-nmap
Auth	JWT (python-jose), bcrypt (passlib)
Deployment	Docker Compose, nginx, systemd

---

Development

# Backend tests
cd backend && source .venv/bin/activate
pytest                    # 40 tests

# Backend lint
ruff check .

# Frontend tests
cd frontend && npm test

# Frontend lint + typecheck
npm run lint && npm run typecheck