Homelable

Homelable is a self-hosted infrastructure visualization solution. It provides a network scanning feature to accelerate the identification of machines and services deployed on your local infrastructure.

Homelable also offers a healthcheck system (WIP) through multiple methods (ping/TCP, /health API, etc.) to get a global overview of online/offline services.

---

Quick Start — Docker

git clone https://github.com/Pouzor/homelable.git
cd homelable
cp .env.example .env
docker compose up -d

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

Change the password before exposing to a network: edit .env and update AUTH_USERNAME / AUTH_PASSWORD_HASH.

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

⚠️ Keep the single quotes around the hash value in .env — bcrypt hashes contain $ characters that Docker Compose would otherwise misinterpret.

---

Proxmox LXC Install

Run inside a Debian/Ubuntu LXC container:

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

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

---

Configuration

All configuration is done via .env (copied from .env.example):

SECRET_KEY=change_me_in_production

# Auth — default: admin / admin
AUTH_USERNAME=admin
AUTH_PASSWORD_HASH='$2b$12$...'   # bcrypt hash — keep single quotes

# CIDR ranges to scan
SCANNER_RANGES=["192.168.1.0/24"]

# How often to check node status (seconds)
STATUS_CHECKER_INTERVAL=60

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 Mode

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 and review defaults
uvicorn app.main:app --reload --port 8000

Frontend:

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

Default login: admin / admin

---