[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74937":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":16,"starSnapshotCount":16,"syncStatus":35,"lastSyncTime":36,"discoverSource":37},74937,"homelable","Pouzor\u002Fhomelable","Pouzor","Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring","https:\u002F\u002Fhomelable.net",null,"TypeScript",2033,93,11,20,0,30,69,278,90,107.92,"MIT License",false,"main",[26,27,28,29,30,31],"diagram","homelab","homelab-infrastructure-observability","network","proxmox-ve","self-hosted","2026-06-12 04:01:16","# Homelable\n\nHomelable is a self-hosted infrastructure visualization solution. It provides a network\u002Fzigbee scanning feature to accelerate the identification of machines, devices and services deployed on your local infrastructure.\n\nHomelable also offers a healthcheck system through multiple methods (ping\u002FTCP, \u002Fhealth API, etc.) to get a global overview of online\u002Foffline services.\n\nYou can also select some pre-built design styles, or personalize each device in your diagram.\n\nIf you just like the design, you can only run the frontend and export your design as PNG.\n\nIf you are running  \u003Cimg width=\"35\" height=\"35\" align=\"middle\" alt=\"New_Home_Assistant_logo\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F3bb17686-c706-40ce-a2d3-57e02378f37c\" \u002F>  Homeassistant, check the [Homelable HA version](https:\u002F\u002Fgithub.com\u002FPouzor\u002Fhomelable-hacs) (via HACS)\n\n\n---\n\n## Screenshots\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fhomelable1.png\" alt=\"Homelable canvas overview\" width=\"100%\" \u002F>\n  \u003Cimg src=\"docs\u002Fhomelable2.png\" alt=\"Homelable node detail\" width=\"100%\" \u002F>\n  \u003Cimg src=\"docs\u002Fhomelable4.png\" alt=\"Homelable edit pannel\" width=\"48%\" \u002F>\n  \u003Cimg width=\"48%\" alt=\"Homelable Zigbee Network\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F06caab68-6637-4dda-ab16-7e83f63d3972\" \u002F>\n\n\u003C\u002Fp>\n\n---\n\n## Installation\n\nDocker, Proxmox LXC, build from source, configuration, and development setup are all covered in **[INSTALLATION.md](.\u002FINSTALLATION.md)**.\n\n---\n\n## Network Scanner\n\nThe 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.\n\n### Triggering a scan\n\nTo save you time when mapping your infrastructure, Homlable can scan your network and report all the services it detects. It can also identify them, saving you even more time.\nClick **Scan Network** in the sidebar. The Scan History tab opens automatically and refreshes every 3 seconds until the scan completes.\n\n### macOS \u002F root privileges\n\nSome 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:\n\n```bash\ncd backend\nsudo python ..\u002Fscripts\u002Frun_scan.py 192.168.1.0\u002F24\n\n# Multiple ranges:\nsudo python ..\u002Fscripts\u002Frun_scan.py 192.168.1.0\u002F24 10.0.0.0\u002F24\n```\n\nResults are written directly to the database and appear as Pending Devices in the UI without restarting the backend.\n\n> On Linux the backend process itself can be given the `NET_RAW` capability instead of running as root:\n> ```bash\n> sudo setcap cap_net_raw+ep $(which nmap)\n> ```\n\n---\n\n## Node Check Methods\n\nHomelable continuously monitors your nodes and displays their live status (online \u002F offline \u002F unknown) directly on the canvas. Each node can be configured with an independent check method suited to the service it runs.\n\n| Method | Description |\n|--------|-------------|\n| `ping` | ICMP ping |\n| `http` | GET request, success if status \u003C 500 |\n| `https` | GET with TLS verify |\n| `tcp` | TCP connect (target: `host:port`) |\n| `ssh` | TCP connect to port 22 |\n| `prometheus` | GET `\u002Fmetrics` |\n| `health` | GET `\u002Fhealth` |\n\n---\n\n## Zigbee2MQTT Import\n\nHomelable can connect directly to your MQTT broker and import your Zigbee network topology from **Zigbee2MQTT**, placing each device on the canvas as a typed node.\n\n### Prerequisites\n\n- A running **MQTT broker** (e.g. Mosquitto) accessible from the Homelable host\n- **Zigbee2MQTT** connected to the broker with at least one device paired\n\n### Usage\n\n1. Click **Zigbee Import** in the left sidebar (below \"Scan Network\")\n2. Enter your broker host, port (default `1883`), optional credentials, and base topic (default `zigbee2mqtt`)\n3. Click **Test Connection** to verify reachability, then **Fetch Devices**\n4. Select the devices you want from the grouped list (Coordinator \u002F Router \u002F End Device)\n5. Click **Add N to Canvas** — devices are placed in a grid with IoT edges\n\n### Node Types\n\n| Type | Z2M Device | Icon |\n|------|-----------|------|\n| `zigbee_coordinator` | Coordinator | Network hub |\n| `zigbee_router` | Router (mains-powered) | Radio |\n| `zigbee_enddevice` | End Device (battery) | Antenna |\n\nHierarchy is set automatically: coordinator → routers → end devices (`parent_id`).\nLQI (Link Quality Indicator) is stored as a node property.\n\n> **Full documentation:** [docs\u002Fzigbee-import.md](.\u002Fdocs\u002Fzigbee-import.md)\n\n---\n\n## Live View (read-only public canvas)\n\nLive View lets you share a read-only snapshot of your canvas with anyone on your network — no login required. It is disabled by default.\n\n### Activation\n\nAdd LIVEVIEW_KEY to your .env:\n\n`LIVEVIEW_KEY=your-secret-key`\n\n\nThen restart the backend:\n\n`docker compose restart backend`\n\n### Usage\n\nUse this URL to view your canvas:\n\nhttp:\u002F\u002F\u003Cyour-homelab-ip>\u002Fview?key=your-secret-key\n\nThe page shows your canvas in pan\u002Fzoom-only mode — no editing, no credentials needed. Clicking a node that has an IP opens it in a new tab.\n\n---\n\n## Gethomepage Widget (read-only stats)\n\nHomelable can expose a small JSON stats endpoint that [gethomepage](https:\u002F\u002Fgethomepage.dev) consumes through its built-in `customapi` widget. Disabled by default.\n\n### Activation\n\nAdd `HOMEPAGE_API_KEY` to your `.env`:\n\n`HOMEPAGE_API_KEY=your-secret-key`\n\nRestart the backend (`docker compose restart backend`).\n\n### Endpoint\n\n`GET \u002Fapi\u002Fv1\u002Fstats\u002Fsummary` — requires header `X-API-Key: your-secret-key`. Returns:\n\n```json\n{\n  \"nodes\": 12,\n  \"online\": 9,\n  \"offline\": 2,\n  \"unknown\": 1,\n  \"pending_devices\": 3,\n  \"zigbee_devices\": 5,\n  \"last_scan_at\": \"2026-05-14T10:00:00+00:00\"\n}\n```\n\n### gethomepage `services.yaml` snippet\n\n```yaml\n- Homelab:\n    - Homelable:\n        icon: mdi-lan\n        href: http:\u002F\u002Fhomelable.local:3000\n        widget:\n          type: customapi\n          url: http:\u002F\u002Fhomelable.local:8000\u002Fapi\u002Fv1\u002Fstats\u002Fsummary\n          method: GET\n          headers:\n            X-API-Key: your-secret-key\n          mappings:\n            - field: nodes           ; label: Nodes\n            - field: online          ; label: Online\n            - field: offline         ; label: Offline\n            - field: pending_devices ; label: Pending\n            - field: zigbee_devices  ; label: Zigbee\n            - field: last_scan_at    ; label: Last scan\n```\n\nThe backend port (`8000`) must be reachable from your gethomepage container.\n\n---\n\n## MCP Server (AI Integration) (optional)\n\nHomelable can exposes a [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io) server so any MCP-compatible AI client (Claude Code, Claude Desktop, Open WebUI…) can read your homelab topology and act on it.\n\n### What the AI can do\n\n| | Action |\n|---|---|\n| **Read** | List all nodes, edges, full canvas, pending devices, scan history |\n| **Write** | Add \u002F update \u002F delete nodes and edges, trigger a network scan, approve or hide discovered devices |\n\n### Setup\n\n**1. Add the keys to your `.env`:**\n\n```env\n# Authenticates AI clients (Claude Code, etc.) → MCP server\nMCP_API_KEY=mcp_sk_changeme\n\n# Authenticates MCP server → backend (internal Docker network only, never exposed)\nMCP_SERVICE_KEY=svc_changeme\n\n# Generate both with:\n# python3 -c \"import secrets; print(secrets.token_hex(32))\"\n```\n\nNo plain-text passwords involved — `AUTH_PASSWORD_HASH` is only used for the web UI login.\n\n**2. Start the MCP service:**\n\n```bash\ndocker compose up -d mcp\n# MCP server is now listening on http:\u002F\u002F\u003Cyour-homelab-ip>:8001\n```\n\n**3. Configure your AI client:**\n\n**Claude Code** — run this command in your terminal:\n```bash\nclaude mcp add --transport sse homelable http:\u002F\u002F\u003Cyour-homelab-ip>:8001\u002Fmcp \\\n  --header \"X-API-Key: mcp_sk_yourkey\"\n```\n\nOr add it manually to `~\u002F.claude.json`:\n```json\n{\n  \"mcpServers\": {\n    \"homelable\": {\n      \"type\": \"sse\",\n      \"url\": \"http:\u002F\u002F\u003Cyour-homelab-ip>:8001\u002Fmcp\",\n      \"headers\": {\n        \"X-API-Key\": \"mcp_sk_yourkey\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop** — edit `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n```json\n{\n  \"mcpServers\": {\n    \"homelable\": {\n      \"type\": \"sse\",\n      \"url\": \"http:\u002F\u002F\u003Cyour-homelab-ip>:8001\u002Fmcp\",\n      \"headers\": {\n        \"X-API-Key\": \"mcp_sk_yourkey\"\n      }\n    }\n  }\n}\n```\n\n### Example prompts\n\n- *\"What nodes are currently offline?\"*\n- *\"Add a new LXC container named `pihole` at 192.168.1.5, connected to my switch.\"*\n- *\"Trigger a network scan on 192.168.1.0\u002F24 and show me the pending devices.\"*\n- *\"Show me the full canvas topology.\"*\n\n### Security\n\n- The MCP server is **not** intended to be exposed to the internet — keep port 8001 firewalled to your LAN.\n- Rotate the key any time by updating `MCP_API_KEY` in `.env` and restarting: `docker compose restart mcp`.\n- The MCP server communicates with the backend over the internal Docker network — the backend API is never directly exposed to MCP clients.\n\n---\n","Homelable 是一个自托管的基础架构可视化解决方案，通过提供网络\u002FZigbee扫描功能来加速识别本地基础架构中部署的机器、设备和服务。其核心功能包括实时状态监控（如通过ping\u002FTCP或\u002Fhealth API等多种健康检查方法）和可定制化的设备展示样式。用户可以根据需要选择预设的设计风格或个性化每个设备的显示。此外，它还支持仅运行前端以导出设计为PNG文件，以及与Homeassistant集成的版本。适用于家庭实验室、小型数据中心等场景，帮助维护者清晰地了解网络拓扑结构及各组件的工作状态。",2,"2026-06-11 03:51:28","high_star"]