alvesd/homelab repository overview

⁠HomeLab

A self-hosted, modern dashboard for organizing and monitoring your frequently used links. Built with React, Express, and Tailwind CSS.

⁠Gallery

Screenshots and detailed documentation available in the alvesd/homelab-assets⁠ public repository.

⁠Features

• Link Management — Add, edit, delete, and drag-to-reorder your links
• Link Groups — Organize links into named, color-coded groups with drag-and-drop reordering and cross-group link dragging
• Smart Sorting — Sort by usage frequency within each group (default), alphabetically, or custom drag-and-drop order
• Health Monitoring — Background HTTP health checks with sparkline graphs on each card
• Per-Link Health Config — Toggle health checks per link, set custom health check URLs, per-link SLA target
• Uptime Dashboard — Dedicated page with 24h/7d/30d SLA views: overall uptime %, avg/p95 response times, hourly availability timeline, top-10 slowest response-time chart, and a sortable per-link table with SLA badges
• Wake-On-LAN — Manage WOL targets and wake them with a single click. Add servers by MAC manually, or one-click import them from a connected UniFi controller's clients list. Magic packets broadcast on the host's LAN; remote-subnet wakes work via stateless WOL Agents (WOL_AGENT_MODE=true).
• Web Terminal & Multi-Protocol Remote Access — Built-in browser terminal for accessing the local container shell, establishing SSH connections, opening a graphical VNC desktop, or launching RDP sessions via native URL scheme handoff (rdp://, ms-rdp://). Supports credentials, agent forwarding, keys, agent proxying, and mobile-friendly on-screen keyboard controls (perfect for administering guests from tablets and phones).
• Proxmox VE Management — Manage one or more Proxmox VE clusters from the dashboard: status, VM/LXC inventory, in-browser noVNC console for guests, guest power actions, node reboot/shutdown. Guest rows badge their IP address, snapshot count, and any hardware passthrough (GPU/USB/NIC), and the kebab menu adds snapshot management and hardware editing (cores, memory, boot options, disk grow).
• UniFi Network & Client Telemetry — Connect Site Manager API keys or local controller credentials to surface site metadata, client list with live telemetry (link speeds, switch ports, Wi-Fi signal/RSSI/channel, IP/MAC filtering), device inventory, and single-device reboot.
• Synology Logs — Connect Synology NAS DSM credentials to fetch logs, perform AI-powered log summaries, and run free-form Q&A.
• AI Manager & Multi-Model Intelligence — Automated cross-server log intelligence: 7-day error/warning pattern sweeps across all Synology syslog servers with AI-powered root-cause diagnostic reports and grounded Q&A. Supports Google Gemini, Anthropic Claude, OpenAI, and local Ollama models.
• Cloudflare Integration — Complete suite for DNS CRUD management, Zero-Trust Tunnel status grids with micro-interaction restarts, and real-time GraphQL analytics with searchable firewall event threat logs.
• Portainer — Manage Docker across one or more Portainer servers/endpoints: container inventory, registry image-update detection, and one-click recreate to pull the latest image.
• TrueNAS — Connect TrueNAS SCALE/CORE systems for pool & dataset health, snapshot status, and OS update detection/apply.
• Home Assistant — Embed your Home Assistant dashboard alongside an AI assistant that has live entity states in context — control devices, explain states, and draft/deploy automation scripts in natural language with direct Model Context Protocol (MCP) tool execution.
• System Updates & AutoPilot — Consolidated view of pending updates across Portainer containers, Proxmox guests/hosts, and TrueNAS, with one-click apply streamed to a live terminal, plus a scheduled AutoPilot that applies them automatically (snapshots guests first; never auto-reboots hosts).
• Active/Active HA Clustering — Run multiple nodes behind a load balancer with automated write-owner election, near real-time snapshot replication, and peer-to-peer WebSocket tickets.
• RBAC & Encrypted Backups — Role-Based Access Control (Admin, Operator, Viewer) with granular permission gating. AES-256-GCM encrypted full system and per-user backup export and restore with automated cluster token scrubbing for secure portability.
• In-App Manual Q&A — Access the comprehensive user guide right in the hamburger menu, with an offline PDF exporter and an AI-powered Q&A grounding assistant.
• Mobile Companion App — iOS and Android React Native companion app providing dashboard status parity, biometric secure locking, unified on-demand updates, real-time push alerts, and lock-screen/home widgets.
• Customizable Pages — Toggle and reorder the pages that appear in the top-left hamburger menu per user.
• Google OAuth — Sign in with Google alongside username/password auth
• AI Integration — Smart link suggestions, background generation, and link organization powered by your choice of AI provider.
• Custom Icons — Upload custom icons or choose from presets, shared across all users
• Weather Widget — Current conditions and forecast based on geolocation
• Customizable Backgrounds — Choose from preset images, colors, or upload your own
• Multi-User Support — Admin user management with role-based access
• Import/Export — Bulk import links from text or browser bookmark HTML files
• Grid & List Views — Toggle between grid and list layout
• Drag & Drop — Reorder links with drag-and-drop in edit mode
• Docker Ready — Published linux/amd64 image built on a Chainguard distroless Node base (0-CVE, non-root, no shell), CVE-gated by Trivy on every build. For arm64 hosts (Raspberry Pi, Apple Silicon) build the image locally from this repo — the Dockerfile is architecture-neutral.

⁠Key Features Highlight

HomeLab combines a modern link dashboard with powerful server management tools:

• Dashboard — Organize and access your favorite links with color-coded groups, drag-and-drop reordering, and smart sorting
• Active/Active HA Clustering — Multi-node deployment with automated write-owner election, replication, and proxying
• Wake-On-LAN — Manage WOL targets manually or import them from a connected UniFi controller, then wake them with a click. Remote-subnet wakes are forwarded through stateless WOL Agents.
• Uptime Monitoring — Track health and SLA metrics for all your services with 30-day historical data and response time graphs
• Web Terminal & Multi-Protocol Remote Access — SSH and VNC access directly in your browser, RDP Quick-Connect with native protocol handoff, agent forwarding, private key mounting, and mobile-friendly on-screen keyboard controls for VNC sessions
• Proxmox Cluster Management — Manage VMs and LXC containers across one or more PVE clusters with an in-browser noVNC console
• UniFi Network — Multi-site UniFi dashboard with WAN status, device table, live client telemetry (link speeds, switch ports, Wi-Fi signal/channel), and one-click device reboot
• Synology Logs & AI Root Cause Analysis — Pull DSM logs into the browser with severity filters and multi-model AI-powered summarization and diagnostic reporting
• Cloudflare DNS & Tunnels — Manage DNS records CRUD, monitor Zero-Trust tunnels with dynamic uptime logs and confirmation-free inline restarts, and track GraphQL WAF analytics with interactive charts and IP search.
• AI Integration & Q&A Assistant — Multi-model AI link suggestions, smart organization, and grounded Q&A over Synology logs and the in-app User Manual (Gemini, Claude, OpenAI, Ollama)
• Role-Based Access Control (RBAC) — Admin, Operator, and Viewer roles with granular permissions across infrastructure controls and logs
• Encrypted System Backups — AES-256-GCM encrypted backup and restore with cluster token scrubbing
• Google OAuth — Sign in with Google alongside traditional username/password auth
• Custom Themes — Light and dark modes with customizable backgrounds and color schemes
• Health Checks — Automatic HTTP monitoring with per-link SLA targets and uptime reporting
• Per-User Page Layout — Toggle and reorder the hamburger menu pages each user sees

⁠Quick Start

⁠Docker (recommended)

docker run -d \
  -p 80:3000 \
  -v $(pwd)/data:/app/data \
  -e APP_URL=http://localhost:80 \
  -e SESSION_SECRET=your-random-secret \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=changeme \
  alvesd/homelab:latest

Then open http://localhost:80⁠.

⁠Docker Compose

Create a docker-compose.yml file in your project directory:

version: '3.8'

services:
  homelab:
    image: alvesd/homelab:latest

    ports:
      - "80:3000"

    environment:
      NODE_ENV: production
      APP_URL: http://localhost:80
      SESSION_SECRET: your-random-secret-here-change-in-production
      ADMIN_USERNAME: admin
      ADMIN_PASSWORD: admin
      # Optional:
      # GOOGLE_CLIENT_ID: your-client-id
      # GOOGLE_CLIENT_SECRET: your-client-secret
      # GEMINI_API_KEY: your-key
    volumes:
      - ./data:/app/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Then run:

docker-compose up -d

⁠Environment Variables

⁠Google OAuth Setup

To enable Sign in with Google:

1. Create an OAuth client in Google Cloud Console⁠ (Web application type)
2. Add your APP_URL to Authorized JavaScript origins
3. Add {APP_URL}/auth/google/identity/callback to Authorized redirect URIs
4. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in your environment

Users must be pre-created by an admin with a matching Google email before they can sign in with Google. Link a Google email to a user in Settings > Users.

⁠Health Monitoring

The server performs background HTTP health checks on all links at a configurable interval.

⁠Global Settings (Admin)

Configure in Settings > Global:

• Enable/Disable — Toggle health monitoring on or off for the entire instance
• Check Interval — Set how often links are checked (1–60 minutes, default: 15)

⁠Per-Link Settings

Configure when adding or editing a link:

• Health Check Toggle — Enable or disable health checks for individual links
• Custom Health Check URL — Optionally use a different URL for health checks (e.g., an API health endpoint like https://api.example.com/health instead of the main page URL)
• SLA Target — Per-link uptime target (0–100%, default 99.9). Drives the green/red badge on the Uptime dashboard

⁠How It Works

• The server sends HTTP HEAD requests to each link (falls back to GET if HEAD fails)
• Any HTTP response (including 4xx) counts as reachable — only 5xx responses and network/timeout failures count as downtime, so auth-gated endpoints (e.g., a 403 login redirect) don't skew your SLA
• Raw results are retained for 30 days and drive both the per-card sparkline and the Uptime dashboard
• Green area shows response time; red dots indicate downtime
• Hover over the sparkline to see exact timestamps and response times
• Links with health checks disabled are skipped, and their historical entries are dropped from the Uptime dashboard

⁠Uptime Dashboard

Open the Uptime page from the hamburger menu (top-left) for a full SLA view across all monitored links:

• Time range selector — 24h / 7d / 30d segmented control
• Summary cards — Overall uptime %, meeting-SLA count, avg response, p95 response, incident count
• Response-time chart — Top 10 slowest links plotted hourly
• Availability timeline — Stacked bar chart of up/down checks per hour
• Per-link table — Sortable by name, uptime %, avg response, p95, or incident count. Each row shows a green badge when uptime meets the link's SLA target and red when it doesn't.

⁠Wake-On-LAN

Discover and wake machines on your LAN from the hamburger menu in the top-left.

⁠How it works

• WOL targets are added either manually (admin clicks Add Server and enters a MAC) or by importing from UniFi (the Add from UniFi picker lists currently-connected controller clients and one-clicks each onto the WOL list)
• Servers are stored globally in data/db.json and shown to every user
• Click the pencil icon next to a hostname to rename a server
• The Wake button broadcasts a magic packet via the wake-on-lan⁠ package — routed through a registered WOL Agent if the target lives on a remote subnet, otherwise via local broadcast
• Multi-select wake: tick the checkbox next to multiple servers and click Wake Selected to fire magic packets to all of them in parallel
• Confirmation popup: every wake opens a modal with a per-server success/failure breakdown so you always know which packets actually went out

⁠Requirements

• Magic packets need to reach your LAN's broadcast domain — the default -p 80:3000 mapping works for most setups, since the wake call traverses the host's network stack. Use --network host only if your Docker NAT swallows broadcast traffic
• The target machines must have WOL enabled in BIOS/UEFI and in their OS network adapter settings

⁠Multi-subnet WOL Agents

To wake machines on other subnets (separate VLANs, remote sites), run the same image as a stateless WOL Agent on a host inside that subnet. The agent self-registers with the central homelab and forwards /wake magic-packet calls. (LAN discovery from agents was removed alongside arp-scan; manual entry / UniFi import covers discovery on both local and remote subnets.)

docker run -d \
  -e WOL_AGENT_MODE=true \
  -e WOL_AGENT_TOKEN=long-random-string \
  -e HOMEPAGE_URL=http://homelab.lan:80 \
  alvesd/homelab:latest

Or in docker-compose.yml (see the commented wol-agent block in the repo's compose file):

wol-agent:
  image: alvesd/homelab:latest
  environment:
    WOL_AGENT_MODE: "true"
    WOL_AGENT_TOKEN: "long-random-string"
    HOMEPAGE_URL: "http://homelab.lan:80"
    # Optional:
    # WOL_AGENT_PORT: "9999"
    # WOL_AGENT_NAME: "garage-rack"
  restart: unless-stopped

Required env vars:

• WOL_AGENT_MODE=true — switches the image into headless agent mode
• WOL_AGENT_TOKEN=… — Bearer token the homelab will use to call the agent
• HOMEPAGE_URL=… — where to self-register (e.g. http://192.168.1.10:80)

Optional env vars:

• WOL_AGENT_PORT — defaults to 9999
• WOL_AGENT_NAME — display label in the UI; defaults to the OS hostname

The agent prints its name, IP, port, token, subnet, and the registered homelab URL to its container logs on startup. It heartbeats every 5 minutes; the UI shows agents as offline after ~12 minutes without a heartbeat. Agents are stateless — no volume needed.

⁠Troubleshooting WOL Agents

If your agent never appears in the WOL Agents list, check its logs (docker logs <container>):

• fetch failed / ECONNREFUSED — HOMEPAGE_URL is wrong or unreachable. The most common mistake is omitting the port: bare http://homelab.lan resolves to port 80, but the homelab usually listens on :80. Use http://homelab.lan:80 (or whatever port the central instance is bound to). Verify connectivity from the agent host with curl http://homelab.lan:80/api/wol/agents/register -X POST.
• register POST … → 404 — The central homelab is running an older image without the /api/wol/agents/register endpoint. Pull alvesd/homelab:latest and redeploy the central instance.
• register POST … → 401 — Token mismatch. Agent registration is authenticated: the agent's WOL_AGENT_TOKEN must match the one set on the central homelab. Set the same WOL_AGENT_TOKEN on the central instance and on each agent.
• register POST … → 503 — The central homelab has no WOL_AGENT_TOKEN configured, so it refuses all agent registrations. Set WOL_AGENT_TOKEN on the central instance (matching your agents) and redeploy.
• HOMEPAGE_URL must start with http:// or https:// — Add the scheme.
• could not detect a local subnet — The agent couldn't autodetect a non-loopback IPv4 address. Set WOL_AGENT_SUBNET explicitly (e.g. 192.168.5.0/24), or run the agent with --network host so it sees the host's real interfaces.
• Agent registers, then goes offline after ~12 minutes — Heartbeats are failing. Check the agent logs for warnings after the initial registered with … line; the same network/URL diagnostics apply.

⁠Web Terminal & Multi-Protocol Remote Access (SSH / VNC / RDP)

Access the built-in browser terminal and multi-protocol connection hub from the Hamburger menu.

⁠Features

• Local Shell: Instantly drop into the container's shell (/bin/bash).
• SSH Client: Connect to arbitrary hosts using username/password, SSH key, or agent forwarding.
• VNC Client: Open a graphical desktop in the browser (powered by noVNC⁠) against any RFB-speaking server — x11vnc, TigerVNC, macOS Screen Sharing, Windows UltraVNC, Proxmox/ESXi consoles, etc. Works with the same saved-connection list, group sidebar, and icon presets as SSH. Port defaults to 5901 and is freely editable.
  • Touch & Mobile Keyboard Support: On mobile devices, tap the floating keyboard button (⌨) at the middle-right of the VNC viewport to summon the system soft keyboard and an expanded toolbar. The toolbar provides quick access to modifiers (Ctrl, Alt, Shift, Super), special keys (Esc, Tab, arrows, F1–F12), and the Ctrl+Alt+Delete sequence. Modifier keys latch, so you can tap Ctrl once, then tap another key to send Ctrl+key. Perfect for administering headless servers, VMs, or graphical desktops from a tablet or phone.
• RDP Quick-Connect & URL Scheme Handoff: Launch Remote Desktop Protocol sessions via native browser scheme handlers (rdp:// and ms-rdp://) into clients like Microsoft Remote Desktop, Windows App, or FreeRDP. Includes one-click IP/port copy and clipboard credential copy for streamlined workstation connections.
• Agent Proxying: Just like Wake-On-LAN and SSH, VNC sessions can seamlessly proxy through remote WOL Agents to reach machines on isolated networks — the agent opens a TCP connection on the target LAN and pipes raw RFB bytes back through the WebSocket.
• Connection Groups: Save and organize your frequently accessed servers with custom icons, color badges, and group tags.

⁠Authentication

If your target servers require SSH keys, you can mount them into the Docker container by mapping a volume:

-v ~/.ssh/id_ed25519:/root/.ssh/id_ed25519:ro

Or you can use SSH Agent forwarding if enabled on the host network.

VNC and SSH passwords are AES-256-GCM-encrypted in db.json. The plaintext password is only handed to the browser over the single-use, ticketed WebSocket just before the RFB handshake — it never appears in a URL query string.

⁠Proxmox

Manage one or more Proxmox VE clusters from the Proxmox page in the hamburger menu.

⁠Capabilities

• Cluster snapshot — Per-node status (online/offline, uptime, CPU, memory, rootfs), VM and LXC inventories with state badges, polled every 5 s while the tab is visible
• Guest actions — Start, stop, reboot, shutdown, suspend, resume, migrate, clone, delete (with optional purge) — all return a Proxmox task UPID that the UI polls until success or error
• In-browser console — One-click noVNC console for any guest, tunneled through the homelab's WebSocket — no separate Proxmox login or cert prompts in the browser
• Node-level actions — Reboot or shutdown a whole node from the Nodes table
• Guest badges — Each guest row shows its IP address (VMs via the QEMU guest agent, LXC via Proxmox — container/VPN bridges like docker0 are filtered out), snapshot count, and one badge per passed-through device (GPU, USB, NIC, Storage). VMs without a guest agent are flagged so you know why no IP is shown
• Snapshot management — List and delete a guest's snapshots, bulk-clean the automatic pre-update snapshots, and set how many to retain per guest
• Hardware editing — Change cores, sockets, memory, balloon/swap, name/hostname, boot-at-start and start order, and the guest description (rendered as formatted notes); grow a disk by a set number of GiB. Only changed fields are sent, and Proxmox's concurrent-edit guard is respected
• Detailed errors — When Proxmox rejects an action, the real reason from PVE is surfaced instead of a generic failure
• Fallback hosts — Give a cluster additional hosts so the page keeps working when the primary member is unreachable
• Multi-cluster — Add as many clusters as you want (work, home, edge sites); each renders its own snapshot

⁠Authentication

Two modes via Settings → click Add Proxmox Cluster:

• API Token (recommended) — Bypasses two-factor auth, no CSRF round-trip. Generate at Datacenter → Permissions → API Tokens. Format: USER@REALM!TOKENID. Either grant the token Sys.Audit on / or uncheck "Privilege Separation".
• Username + Password — Standard PVE ticket flow. Two-factor auth is not supported in this mode; use API tokens if your account has TFA enabled.

Self-signed certificates are allowed by default (typical homelab setup) — uncheck Verify TLS in the form. All credentials are AES-256-GCM-encrypted at rest.

⁠UniFi Network

Connect Ubiqu