Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

feat: import hosts/VMs/LXC from Proxmox VE with optional auto-sync

Pouzorab36ba6f81d9
diff --git a/.env.example b/.env.example
index 9dbfdcf..a53f833 100644
--- a/.env.example
+++ b/.env.example
@@ -46,3 +46,15 @@ MCP_SERVICE_KEY=svc_changeme
# the same value in the `X-API-Key` header.
# Generate: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
# HOMEPAGE_API_KEY=
+
+# Proxmox VE import — pull hosts/VMs/LXC from the Proxmox REST API.
+# The token is a credential: kept in memory only, never written to disk by the
+# app, never returned by any API. Create it under Datacenter → Permissions →
+# API Tokens and grant the read-only PVEAuditor role at path "/".
+# Token id format: user@realm!tokenname (e.g. root@pam!homelable).
+# Required only for auto-sync; one-off imports can pass the token in the dialog.
+# PROXMOX_TOKEN_ID=root@pam!homelable
+# PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+# PROXMOX_HOST=192.168.1.10
+# PROXMOX_PORT=8006
+# PROXMOX_VERIFY_TLS=true # set false only for self-signed certs
diff --git a/FEATURES.md b/FEATURES.md
index 0b15749..eb68124 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -21,13 +21,14 @@ Here's what Homelable can do. One line on what each feature is, then how to swit
7. [Network Scanner (IP import)](#7-network-scanner-ip-import-)
8. [Zigbee Import](#8-zigbee-import-)
9. [Z-Wave Import](#9-z-wave-import-)
-10. [Device Inventory](#10-device-inventory-)
-11. [Live Status Monitoring](#11-live-status-monitoring-)
-12. [Export (PNG / SVG / YAML / Markdown)](#12-export)
-13. [Live View (read-only public canvas)](#13-live-view-)
-14. [Gethomepage Widget](#14-gethomepage-widget-)
-15. [MCP Server (AI integration)](#15-mcp-server-)
-16. [Settings & Shortcuts](#16-settings--shortcuts)
+10. [Proxmox VE Import](#10-proxmox-ve-import-)
+11. [Device Inventory](#11-device-inventory-)
+12. [Live Status Monitoring](#12-live-status-monitoring-)
+13. [Export (PNG / SVG / YAML / Markdown)](#13-export)
+14. [Live View (read-only public canvas)](#14-live-view-)
+15. [Gethomepage Widget](#15-gethomepage-widget-)
+16. [MCP Server (AI integration)](#16-mcp-server-)
+17. [Settings & Shortcuts](#17-settings--shortcuts)
---
@@ -140,7 +141,21 @@ Nodes: `zwave_coordinator` / `zwave_router` / `zwave_enddevice`. The hierarchy c
---
-## 10. Device Inventory 🔒
+## 10. Proxmox VE Import 🔒
+
+**What:** Pull your **Proxmox VE** inventory (hosts, VMs, LXC) in over the Proxmox REST API — typed, named nodes with run state and hardware specs. Optional scheduled **auto-sync**; guest IPs already found by a scan are merged, not duplicated.
+
+**Use:**
+1. Create a read-only API token in Proxmox (Datacenter → Permissions → API Tokens, role `PVEAuditor`).
+2. Sidebar → **Proxmox Import**.
+3. Enter host, port (default `8006`), and the token (`user@realm!tokenid` + secret) — or leave blank to use the server token.
+4. **Test Connection** → send to **Pending** or the **Canvas** → import → pick devices → **Add N to Canvas**.
+
+Nodes: `proxmox` (host) / `vm` / `lxc`, linked host→guest by a `virtual` edge. The token is env-only, never stored on disk, never returned by the API. Enable auto-sync from **Settings** once `PROXMOX_TOKEN_ID` / `PROXMOX_TOKEN_SECRET` are set. More: [docs/proxmox-import.md](./docs/proxmox-import.md).
+
+---
+
+## 11. Device Inventory 🔒
**What:** The holding pen for everything found by a scan or import that isn't on the canvas yet, plus a separate **Hidden Devices** list.
@@ -151,7 +166,7 @@ Nodes: `zwave_coordinator` / `zwave_router` / `zwave_enddevice`. The hierarchy c
---
-## 11. Live Status Monitoring 🔒
+## 12. Live Status Monitoring 🔒
**What:** Keeps checking each node and shows its status (🟢 online / 🔴 offline / ⚫ unknown) right on the canvas.
@@ -172,7 +187,7 @@ Nodes: `zwave_coordinator` / `zwave_router` / `zwave_enddevice`. The hierarchy c
---
-## 12. Export
+## 13. Export
**What:** Get your canvas out as a picture or as structured data.
@@ -184,7 +199,7 @@ Nodes: `zwave_coordinator` / `zwave_router` / `zwave_enddevice`. The hierarchy c
---
-## 13. Live View 🔒
+## 14. Live View 🔒
**What:** A read-only, no-login snapshot of a canvas you can share on your LAN. Off by default.
@@ -196,7 +211,7 @@ Pan and zoom only, no editing. Click a node with an IP and it opens in a new tab
---
-## 14. Gethomepage Widget 🔒
+## 15. Gethomepage Widget 🔒
**What:** A tiny JSON stats endpoint for [gethomepage](https://gethomepage.dev)'s `customapi` widget. Off by default.
@@ -208,7 +223,7 @@ Widget snippet lives in the [README](./README.md#gethomepage-widget-read-only-st
---
-## 15. MCP Server 🔒
+## 16. MCP Server 🔒
**What:** A [Model Context Protocol](https://modelcontextprotocol.io) server so an MCP client (Claude Code, Claude Desktop, Open WebUI…) can read and change your topology. Optional, runs as its own service.
@@ -226,7 +241,7 @@ The AI can list nodes/edges/canvas/pending/scans, add/update/delete nodes and ed
---
-## 16. Settings & Shortcuts
+## 17. Settings & Shortcuts
**What:** App config and keyboard shortcuts.
diff --git a/README.md b/README.md
index 9b147a9..8118960 100644
--- a/README.md
+++ b/README.md
@@ -160,6 +160,37 @@ Hierarchy is set automatically: controller → routers → end devices (`parent_
---
+## Proxmox VE Import
+
+Homelable can import your **Proxmox VE** inventory over the Proxmox REST API — hosts, VMs and LXC containers arrive as typed, named nodes with run state and hardware specs, and can auto-sync on a schedule. Guest IPs that were already found by a network scan are merged in place (no duplicates).
+
+### Prerequisites
+
+- A reachable **Proxmox VE** host (default API port `8006`)
+- A **Proxmox API token** with the read-only **`PVEAuditor`** role (Datacenter → Permissions → API Tokens)
+
+### Usage
+
+1. Click **Proxmox Import** in the left sidebar (below "Z-Wave Import")
+2. Enter the host, port (default `8006`), and API token (`user@realm!tokenid` + secret) — or leave the token blank to use the server-configured one
+3. Click **Test Connection** to verify reachability + token
+4. Choose a target — **Pending section** or **Canvas directly** — then **Import to Pending** / **Fetch Inventory**
+5. Select the devices from the grouped list (Hosts / Virtual Machines / LXC Containers) and click **Add N to Canvas**
+
+### Node Types
+
+| Type | Proxmox object | Icon |
+|------|----------------|------|
+| `proxmox` | Host / cluster member | Layers |
+| `vm` | QEMU virtual machine | Box |
+| `lxc` | LXC container | Container |
+
+Each host is linked to its guests with a `virtual` edge. vCPU / RAM / disk are imported as node properties (hidden by default). Enable **auto-sync** from Settings once a server token is configured (`PROXMOX_TOKEN_ID` / `PROXMOX_TOKEN_SECRET`).
+
+> **Full documentation:** [docs/proxmox-import.md](./docs/proxmox-import.md)
+
+---
+
## Live View (read-only public canvas)
Live View lets you share a read-only snapshot of your canvas with anyone on your network — no login required. It is disabled by default.
diff --git a/backend/app/api/routes/proxmox.py b/backend/app/api/routes/proxmox.py
new file mode 100644
index 0000000..6abf8c5
--- /dev/null
+++ b/backend/app/api/routes/proxmox.py
@@ -0,0 +1,379 @@
+"""FastAPI router for Proxmox VE import + auto-sync config.
+
+Fetches hosts/VMs/LXC from the Proxmox REST API and upserts them into the
+pending inventory (same review→approve flow as scans and mesh imports).
+
+Credentials: the API token comes from the request body when provided, else
+falls back to the server-configured env token (``settings.proxmox_token_*``).
+The token is never persisted by the app and never returned by any endpoint.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from sqlalchemy import delete as sa_delete
+from sqlalchemy import or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_user
+from app.core.config import settings
+from app.core.scheduler import reschedule_proxmox_sync, set_proxmox_sync_enabled
+from app.db.database import AsyncSessionLocal, get_db
+from app.db.models import Node, PendingDevice, PendingDeviceLink, ScanRun
+from app.schemas.proxmox import (
+ ProxmoxConfig,
+ ProxmoxConnectionRequest,
+ ProxmoxEdgeOut,
+ ProxmoxImportPendingResponse,
+ ProxmoxImportResponse,
+ ProxmoxNodeOut,
+ ProxmoxTestConnectionResponse,
+)
+from app.schemas.scan import ScanRunResponse
+from app.services.node_dedupe import dedupe_nodes_by_ieee
+from app.services.proxmox_service import (
+ build_proxmox_properties,
+ fetch_proxmox_inventory,
+ merge_proxmox_properties,
+ test_proxmox_connection,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+def _resolve_credentials(payload: ProxmoxConnectionRequest) -> tuple[str, str]:
+ """Pick the API token: request body first, else server env config.
+
+ Raises HTTP 400 when neither carries a token.
+ """
+ token_id = payload.token_id or settings.proxmox_token_id
+ token_secret = payload.token_secret or settings.proxmox_token_secret
+ if not token_id or not token_secret:
+ raise HTTPException(
+ status_code=400,
+ detail="No Proxmox API token provided and none configured on the server.",
+ )
+ return token_id, token_secret
+
+
[email protected]("/test-connection", response_model=ProxmoxTestConnectionResponse)
+async def test_connection_endpoint(
+ payload: ProxmoxConnectionRequest,
+ _: str = Depends(get_current_user),
+) -> ProxmoxTestConnectionResponse:
+ """Validate host reachability + token before importing."""
+ token_id, token_secret = _resolve_credentials(payload)
+ connected, message = await test_proxmox_connection(
+ host=payload.host,
+ port=payload.port,
+ token_id=token_id,
+ token_secret=token_secret,
+ verify_tls=payload.verify_tls,
+ )
+ return ProxmoxTestConnectionResponse(connected=connected, message=message)
+
+
[email protected]("/import", response_model=ProxmoxImportResponse)
+async def import_proxmox(
+ payload: ProxmoxConnectionRequest,
+ _: str = Depends(get_current_user),
+) -> ProxmoxImportResponse:
+ """Fetch the inventory and return nodes + edges ready for canvas drop."""
+ token_id, token_secret = _resolve_credentials(payload)
+ try:
+ nodes_raw, edges_raw = await fetch_proxmox_inventory(
+ host=payload.host,
+ port=payload.port,
+ token_id=token_id,
+ token_secret=token_secret,
+ verify_tls=payload.verify_tls,
+ )
+ except ConnectionError as exc:
+ raise HTTPException(status_code=502, detail=str(exc)) from exc
+ except ValueError as exc:
+ raise HTTPException(status_code=422, detail=str(exc)) from exc
+ except Exception as exc:
+ logger.exception("Unexpected error during Proxmox import")
+ raise HTTPException(status_code=500, detail="Unexpected error during Proxmox import") from exc
+
+ nodes = [ProxmoxNodeOut(**n) for n in nodes_raw]
+ edges = [ProxmoxEdgeOut(**e) for e in edges_raw]
+ return ProxmoxImportResponse(nodes=nodes, edges=edges, device_count=len(nodes))
+
+
[email protected]("/import-pending", response_model=ScanRunResponse)
+async def import_proxmox_to_pending(
+ payload: ProxmoxConnectionRequest,
+ background_tasks: BackgroundTasks,
+ db: AsyncSession = Depends(get_db),
+ _: str = Depends(get_current_user),
+) -> ScanRun:
+ """Queue a Proxmox pending import as a background scan run (kind=proxmox)."""
+ token_id, token_secret = _resolve_credentials(payload)
+ run = ScanRun(
+ status="running",
+ kind="proxmox",
+ ranges=[f"{payload.host}:{payload.port}"],
+ )
+ db.add(run)
+ await db.commit()
+ await db.refresh(run)
+ background_tasks.add_task(
+ _background_proxmox_import,
+ run.id,
+ payload.host,
+ payload.port,
+ token_id,
+ token_secret,
+ payload.verify_tls,
+ )
+ return run
+
+
+async def _background_proxmox_import(
+ run_id: str,
+ host: str,
+ port: int,
+ token_id: str,
+ token_secret: str,
+ verify_tls: bool,
+) -> None:
+ async with AsyncSessionLocal() as db:
+ try:
+ nodes_raw, edges_raw = await fetch_proxmox_inventory(
+ host=host,
+ port=port,
+ token_id=token_id,
+ token_secret=token_secret,
+ verify_tls=verify_tls,
+ )
+ result = await _persist_pending_import(db, nodes_raw, edges_raw)
+ run = await db.get(ScanRun, run_id)
+ if run:
+ run.status = "done"
+ run.devices_found = result.device_count
+ run.finished_at = datetime.now(timezone.utc)
+ await db.commit()
+ except Exception as exc:
+ logger.exception("Proxmox import %s failed", run_id)
+ await db.rollback()
+ run = await db.get(ScanRun, run_id)
+ if run:
+ run.status = "error"
+ run.error = str(exc)[:500]
+ run.finished_at = datetime.now(timezone.utc)
+ await db.commit()
+
+
+async def _persist_pending_import(
+ db: AsyncSession,
+ nodes_raw: list[dict[str, Any]],
+ edges_raw: list[dict[str, Any]],
+) -> ProxmoxImportPendingResponse:
+ """Upsert Proxmox nodes/edges into pending_devices + pending_device_links.
+
+ Two-tier identity (order matters):
+ 1. Match an existing canvas Node or pending row by **IP** (merge into a
+ device previously found by a scan) — never duplicate.
+ 2. Else match by synthetic ``ieee_address`` (``pve-...``).
+
+ Update-in-place only. Nothing is ever deleted; hidden rows stay hidden.
+ """
+ await dedupe_nodes_by_ieee(db)
+
+ pending_created = 0
+ pending_updated = 0
+
+ for n in nodes_raw:
+ ieee = n.get("ieee_address")
+ if not ieee:
+ continue
+ ip = n.get("ip")
+ props = build_proxmox_properties(n)
+
+ # 1) Already on a canvas? Match by ieee OR (ip when known). Refresh in
+ # place: merge properties, adopt the pve identity onto a scanned node,
+ # backfill blank specs/hostname. Do NOT stomp user-set type/status.
+ node_filter = [Node.ieee_address == ieee]
+ if ip:
+ node_filter.append(Node.ip == ip)
+ existing_nodes = (
+ await db.execute(select(Node).where(or_(*node_filter)).order_by(Node.id))
+ ).scalars().all()
+
+ if existing_nodes:
+ for en in existing_nodes:
+ en.properties = merge_proxmox_properties(en.properties, props)
+ if not en.ieee_address:
+ en.ieee_address = ieee
+ if ip and not en.ip:
+ en.ip = ip
+ en.hostname = en.hostname or n.get("hostname")
+ en.cpu_count = en.cpu_count or n.get("cpu_count")
+ en.ram_gb = en.ram_gb or n.get("ram_gb")
+ en.disk_gb = en.disk_gb or n.get("disk_gb")
+ await _ensure_inventory_row(db, ieee, ip, n, props, approved=True)
+ pending_updated += 1
+ continue
+
+ # 2) Not on canvas — upsert the pending inventory row.
+ pending = await _find_pending(db, ieee, ip)
+ if pending is None:
+ db.add(_new_pending(ieee, ip, n, props, status="pending"))
+ pending_created += 1
+ else:
+ _refresh_pending(pending, ieee, ip, n, props)
+ pending_updated += 1
+
+ links_recorded = await _replace_links(db, edges_raw)
+ await db.commit()
+
+ return ProxmoxImportPendingResponse(
+ pending_created=pending_created,
+ pending_updated=pending_updated,
+ links_recorded=links_recorded,
+ device_count=len(nodes_raw),
+ )
+
+
+async def _find_pending(
+ db: AsyncSession, ieee: str, ip: str | None
+) -> PendingDevice | None:
+ filters = [PendingDevice.ieee_address == ieee]
+ if ip:
+ filters.append(PendingDevice.ip == ip)
+ return (
+ await db.execute(select(PendingDevice).where(or_(*filters)))
+ ).scalars().first()
+
+
+def _new_pending(
+ ieee: str, ip: str | None, n: dict[str, Any], props: list[dict[str, Any]], status: str
+) -> PendingDevice:
+ return PendingDevice(
+ ieee_address=ieee,
+ ip=ip,
+ hostname=n.get("hostname"),
+ friendly_name=n.get("label"),
+ suggested_type=n.get("type"),
+ vendor=n.get("vendor"),
+ model=n.get("model"),
+ properties=props,
+ status=status,
+ discovery_source="proxmox",
+ )
+
+
+def _refresh_pending(
+ pending: PendingDevice,
+ ieee: str,
+ ip: str | None,
+ n: dict[str, Any],
+ props: list[dict[str, Any]],
+) -> None:
+ pending.ieee_address = pending.ieee_address or ieee
+ pending.ip = ip or pending.ip
+ pending.hostname = n.get("hostname") or pending.hostname
+ pending.friendly_name = n.get("label") or pending.friendly_name
+ pending.suggested_type = n.get("type") or pending.suggested_type
+ pending.vendor = n.get("vendor") or pending.vendor
+ pending.model = n.get("model") or pending.model
+ pending.properties = merge_proxmox_properties(list(pending.properties or []), props)
+ if pending.status == "approved":
+ # Approved earlier but the canvas Node is gone — revive so it reappears.
+ pending.status = "pending"
+ # hidden stays hidden.
+
+
+async def _ensure_inventory_row(
+ db: AsyncSession,
+ ieee: str,
+ ip: str | None,
+ n: dict[str, Any],
+ props: list[dict[str, Any]],
+ approved: bool,
+) -> None:
+ """Ensure an inventory row exists for a device already on a canvas, so it
+ shows in the inventory with an 'In N canvas' badge. Never changes status."""
+ inv = await _find_pending(db, ieee, ip)
+ if inv is None:
+ db.add(_new_pending(ieee, ip, n, props, status="approved" if approved else "pending"))
+ else:
+ inv.ieee_address = inv.ieee_address or ieee
+ inv.ip = ip or inv.ip
+ inv.hostname = n.get("hostname") or inv.hostname
+ inv.suggested_type = n.get("type") or inv.suggested_type
+ inv.properties = merge_proxmox_properties(list(inv.properties or []), props)
+
+
+async def _replace_links(db: AsyncSession, edges_raw: list[dict[str, Any]]) -> int:
+ """Wipe all proxmox-source links and re-insert the freshly discovered set."""
+ await db.execute(
+ sa_delete(PendingDeviceLink).where(PendingDeviceLink.discovery_source == "proxmox")
+ )
+ recorded = 0
+ seen: set[tuple[str, str]] = set()
+ for e in edges_raw:
+ src = e.get("source")
+ tgt = e.get("target")
+ if not src or not tgt or (src, tgt) in seen:
+ continue
+ seen.add((src, tgt))
+ db.add(
+ PendingDeviceLink(
+ source_ieee=src,
+ target_ieee=tgt,
+ discovery_source="proxmox",
+ )
+ )
+ recorded += 1
+ return recorded
+
+
[email protected]("/config", response_model=ProxmoxConfig)
+async def get_proxmox_config(_: str = Depends(get_current_user)) -> ProxmoxConfig:
+ """Return non-secret Proxmox config. Never includes the token — only whether
+ one is configured on the server."""
+ return ProxmoxConfig(
+ host=settings.proxmox_host,
+ port=settings.proxmox_port,
+ verify_tls=settings.proxmox_verify_tls,
+ sync_enabled=settings.proxmox_sync_enabled,
+ sync_interval=settings.proxmox_sync_interval,
+ token_configured=bool(settings.proxmox_token_id and settings.proxmox_token_secret),
+ )
+
+
[email protected]("/config", response_model=ProxmoxConfig)
+async def save_proxmox_config(
+ payload: ProxmoxConfig,
+ _: str = Depends(get_current_user),
+) -> ProxmoxConfig:
+ """Persist non-secret Proxmox config and apply the auto-sync schedule live.
+
+ The token is NOT accepted here — it is env-only by design.
+ """
+ if payload.sync_enabled and not (settings.proxmox_token_id and settings.proxmox_token_secret):
+ raise HTTPException(
+ status_code=400,
+ detail="Cannot enable auto-sync: no Proxmox API token configured on the server.",
+ )
+ try:
+ settings.proxmox_host = payload.host
+ settings.proxmox_port = payload.port
+ settings.proxmox_verify_tls = payload.verify_tls
+ settings.proxmox_sync_enabled = payload.sync_enabled
+ settings.proxmox_sync_interval = payload.sync_interval
+ settings.save_overrides()
+ set_proxmox_sync_enabled(payload.sync_enabled)
+ if payload.sync_enabled:
+ reschedule_proxmox_sync(payload.sync_interval)
+ except HTTPException:
+ raise
+ except Exception as exc:
+ raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+ return await get_proxmox_config()
diff --git a/backend/app/api/routes/scan.py b/backend/app/api/routes/scan.py
index 2b778d2..501d95e 100644
--- a/backend/app/api/routes/scan.py
+++ b/backend/app/api/routes/scan.py
@@ -367,7 +367,7 @@ async def bulk_approve_devices(
ieee_address=device.ieee_address,
properties=_wireless_properties(
node_type, device.ieee_address, device.vendor, device.model, device.lqi
- ) if is_wireless else build_mac_property(device.mac),
+ ) if is_wireless else merge_mac_property(list(device.properties or []), device.mac),
# Default to ping so the status checker actually polls the new node.
# Without this the scheduler skips it (check_method NULL → no check).
check_method="none" if is_wireless else ("ping" if device.ip else None),
@@ -519,7 +519,10 @@ async def approve_device(
ieee_address=device.ieee_address,
properties=_wireless_properties(
node_data.type, device.ieee_address, device.vendor, device.model, device.lqi
- ) if wireless else merge_mac_property(node_data.properties, _mac),
+ ) if wireless else merge_mac_property(
+ merge_zigbee_properties(list(device.properties or []), node_data.properties or []),
+ _mac,
+ ),
check_method="none" if wireless else (node_data.check_method or ("ping" if node_data.ip else None)),
check_target=None if wireless else node_data.check_target,
design_id=node_design_id,
@@ -609,10 +612,13 @@ async def _resolve_pending_links_for_ieee(
if edge_design_id is None:
first = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
edge_design_id = first.id if first else None
+ # Proxmox host→guest links render as 'virtual' (VM/LXC ↔ host); mesh
+ # links stay 'iot'. Default to iot for any legacy/other source.
+ edge_type = "virtual" if link.discovery_source == "proxmox" else "iot"
edge = Edge(
source=src_id,
target=tgt_id,
- type="iot",
+ type=edge_type,
source_handle="bottom",
target_handle="top-t",
design_id=edge_design_id,
diff --git a/backend/app/core/config.py b/backend/app/core/config.py
index 8dba247..e9b2a0c 100644
--- a/backend/app/core/config.py
+++ b/backend/app/core/config.py
@@ -80,6 +80,19 @@ class Settings(BaseSettings):
# Leave empty to keep the feature disabled (default).
homepage_api_key: str = ""
+ # Proxmox VE import.
+ # Token = a real credential → env/.env ONLY, never persisted by the app to
+ # scan_config.json and never returned by the API. token_id is
+ # 'user@realm!tokenname'; use a read-only PVEAuditor role.
+ proxmox_token_id: str = ""
+ proxmox_token_secret: str = ""
+ # Non-secret connection + auto-sync config (persisted via save_overrides).
+ proxmox_host: str = ""
+ proxmox_port: int = 8006
+ proxmox_verify_tls: bool = True
+ proxmox_sync_enabled: bool = False
+ proxmox_sync_interval: int = 3600 # seconds (floor 300 enforced on write)
+
def _override_path(self) -> Path:
return Path(self.sqlite_path).parent / "scan_config.json"
@@ -108,6 +121,17 @@ class Settings(BaseSettings):
self.scanner_http_probe_enabled = bool(data["scanner_http_probe_enabled"])
if "scanner_http_verify_tls" in data:
self.scanner_http_verify_tls = bool(data["scanner_http_verify_tls"])
+ # Proxmox non-secret config (token stays env-only, never here).
+ if "proxmox_host" in data:
+ self.proxmox_host = str(data["proxmox_host"])
+ if "proxmox_port" in data:
+ self.proxmox_port = int(data["proxmox_port"])
+ if "proxmox_verify_tls" in data:
+ self.proxmox_verify_tls = bool(data["proxmox_verify_tls"])
+ if "proxmox_sync_enabled" in data:
+ self.proxmox_sync_enabled = bool(data["proxmox_sync_enabled"])
+ if "proxmox_sync_interval" in data:
+ self.proxmox_sync_interval = int(data["proxmox_sync_interval"])
except Exception:
pass
@@ -122,6 +146,13 @@ class Settings(BaseSettings):
"scanner_http_ranges": self.scanner_http_ranges,
"scanner_http_probe_enabled": self.scanner_http_probe_enabled,
"scanner_http_verify_tls": self.scanner_http_verify_tls,
+ # Proxmox: only non-secret config. Token fields are intentionally
+ # excluded — they must never be written to disk by the app.
+ "proxmox_host": self.proxmox_host,
+ "proxmox_port": self.proxmox_port,
+ "proxmox_verify_tls": self.proxmox_verify_tls,
+ "proxmox_sync_enabled": self.proxmox_sync_enabled,
+ "proxmox_sync_interval": self.proxmox_sync_interval,
}))
diff --git a/backend/app/core/scheduler.py b/backend/app/core/scheduler.py
index 955c8f2..ed34c15 100644
--- a/backend/app/core/scheduler.py
+++ b/backend/app/core/scheduler.py
@@ -106,6 +106,35 @@ async def _run_service_checks() -> None:
logger.error("Service checks failed for node %s: %s", node_id, exc)
+async def _run_proxmox_sync() -> None:
+ """Fetch the Proxmox inventory and upsert it into pending (auto-sync)."""
+ if not settings.proxmox_sync_enabled:
+ return
+ if not (settings.proxmox_host and settings.proxmox_token_id and settings.proxmox_token_secret):
+ logger.warning("Proxmox auto-sync enabled but host/token not configured — skipping")
+ return
+ # Lazy import to avoid a circular import at module load.
+ from app.api.routes.proxmox import _persist_pending_import
+ from app.services.proxmox_service import fetch_proxmox_inventory
+
+ try:
+ nodes_raw, edges_raw = await fetch_proxmox_inventory(
+ host=settings.proxmox_host,
+ port=settings.proxmox_port,
+ token_id=settings.proxmox_token_id,
+ token_secret=settings.proxmox_token_secret,
+ verify_tls=settings.proxmox_verify_tls,
+ )
+ async with AsyncSessionLocal() as db:
+ result = await _persist_pending_import(db, nodes_raw, edges_raw)
+ logger.info(
+ "Proxmox auto-sync: %d devices (%d new, %d updated)",
+ result.device_count, result.pending_created, result.pending_updated,
+ )
+ except Exception as exc:
+ logger.error("Proxmox auto-sync failed: %s", exc)
+
+
def _add_service_check_job() -> None:
scheduler.add_job(
_run_service_checks,
@@ -117,6 +146,17 @@ def _add_service_check_job() -> None:
)
+def _add_proxmox_sync_job() -> None:
+ scheduler.add_job(
+ _run_proxmox_sync,
+ "interval",
+ seconds=settings.proxmox_sync_interval,
+ id="proxmox_sync",
+ max_instances=1,
+ coalesce=True,
+ )
+
+
def start_scheduler() -> None:
global scheduler
if scheduler.running:
@@ -135,6 +175,8 @@ def start_scheduler() -> None:
)
if settings.service_check_enabled:
_add_service_check_job()
+ if settings.proxmox_sync_enabled:
+ _add_proxmox_sync_job()
scheduler.start()
logger.info("Scheduler started — status checks every %ds", settings.status_checker_interval)
@@ -175,6 +217,31 @@ def set_service_checks_enabled(enabled: bool) -> None:
logger.info("Service checks disabled")
+def reschedule_proxmox_sync(interval_seconds: int) -> None:
+ """Update the Proxmox auto-sync interval on the running scheduler (if enabled)."""
+ if interval_seconds < 300:
+ raise ValueError(f"interval_seconds must be >= 300, got {interval_seconds}")
+ if not scheduler.running:
+ logger.warning("Scheduler not running, skipping reschedule")
+ return
+ if scheduler.get_job("proxmox_sync"):
+ scheduler.reschedule_job("proxmox_sync", trigger="interval", seconds=interval_seconds)
+ logger.info("Proxmox auto-sync rescheduled to every %ds", interval_seconds)
+
+
+def set_proxmox_sync_enabled(enabled: bool) -> None:
+ """Add or remove the Proxmox auto-sync job on the running scheduler."""
+ if not scheduler.running:
+ return
+ job = scheduler.get_job("proxmox_sync")
+ if enabled and not job:
+ _add_proxmox_sync_job()
+ logger.info("Proxmox auto-sync enabled — every %ds", settings.proxmox_sync_interval)
+ elif not enabled and job:
+ scheduler.remove_job("proxmox_sync")
+ logger.info("Proxmox auto-sync disabled")
+
+
def stop_scheduler() -> None:
if scheduler.running:
scheduler.shutdown(wait=False)
diff --git a/backend/app/db/database.py b/backend/app/db/database.py
index 2ffeaae..76470d6 100644
--- a/backend/app/db/database.py
+++ b/backend/app/db/database.py
@@ -115,6 +115,8 @@ async def init_db() -> None:
await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN right_handles INTEGER NOT NULL DEFAULT 0")
with suppress(OperationalError):
await conn.exec_driver_sql("ALTER TABLE pending_devices ADD COLUMN discovery_source TEXT")
+ with suppress(OperationalError):
+ await conn.exec_driver_sql("ALTER TABLE pending_devices ADD COLUMN properties JSON")
with suppress(OperationalError):
await conn.exec_driver_sql("ALTER TABLE scan_runs ADD COLUMN kind TEXT NOT NULL DEFAULT 'ip'")
# --- Zigbee schema migrations (logged variant per CLAUDE.md feedback) ---
@@ -162,6 +164,7 @@ async def init_db() -> None:
"model VARCHAR,"
"vendor VARCHAR,"
"lqi INTEGER,"
+ "properties JSON,"
"discovered_at DATETIME"
")"
)
diff --git a/backend/app/db/models.py b/backend/app/db/models.py
index 144f976..ac99f89 100644
--- a/backend/app/db/models.py
+++ b/backend/app/db/models.py
@@ -126,6 +126,10 @@ class PendingDevice(Base):
model: Mapped[str | None] = mapped_column(String, nullable=True)
vendor: Mapped[str | None] = mapped_column(String, nullable=True)
lqi: Mapped[int | None] = mapped_column(Integer, nullable=True)
+ # Display properties carried from discovery (e.g. Proxmox specs: CPU/RAM/Disk,
+ # VMID). Generic NodeProperty shape {key,value,icon,visible}; merged into the
+ # Node's properties on approve. Empty for scan/mesh sources that don't set it.
+ properties: Mapped[list[Any]] = mapped_column(JSON, default=list)
discovered_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
# Transient (not persisted): populated per-request by the scan routes to report
diff --git a/backend/app/main.py b/backend/app/main.py
index 4ca6f6d..368a490 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -7,7 +7,21 @@ from typing import Any
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
-from app.api.routes import auth, canvas, designs, edges, liveview, media, nodes, scan, stats, status, zigbee, zwave
+from app.api.routes import (
+ auth,
+ canvas,
+ designs,
+ edges,
+ liveview,
+ media,
+ nodes,
+ proxmox,
+ scan,
+ stats,
+ status,
+ zigbee,
+ zwave,
+)
from app.api.routes import settings as settings_routes
from app.core.config import settings
from app.core.scheduler import start_scheduler, stop_scheduler
@@ -58,6 +72,7 @@ app.include_router(settings_routes.router, prefix="/api/v1/settings", tags=["set
app.include_router(liveview.router, prefix="/api/v1/liveview", tags=["liveview"])
app.include_router(zigbee.router, prefix="/api/v1/zigbee", tags=["zigbee"])
app.include_router(zwave.router, prefix="/api/v1/zwave", tags=["zwave"])
+app.include_router(proxmox.router, prefix="/api/v1/proxmox", tags=["proxmox"])
app.include_router(stats.router, prefix="/api/v1/stats", tags=["stats"])
app.include_router(media.router, prefix="/api/v1/media", tags=["media"])
diff --git a/backend/app/schemas/proxmox.py b/backend/app/schemas/proxmox.py
new file mode 100644
index 0000000..8ebf67d
--- /dev/null
+++ b/backend/app/schemas/proxmox.py
@@ -0,0 +1,75 @@
+"""Pydantic v2 schemas for Proxmox VE import.
+
+Token fields are accepted on requests only and are optional — when omitted the
+backend falls back to the server-configured token (env). No response schema ever
+carries a token; secrets are kept out of responses by structural omission.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class ProxmoxConnectionRequest(BaseModel):
+ host: str = Field(..., description="Proxmox VE host or IP")
+ port: int = Field(8006, ge=1, le=65535, description="Proxmox API port")
+ token_id: str | None = Field(
+ None, description="API token id 'user@realm!tokenname' (falls back to server env)"
+ )
+ token_secret: str | None = Field(
+ None, description="API token secret (falls back to server env)"
+ )
+ verify_tls: bool = Field(True, description="Verify the Proxmox TLS certificate")
+
+
+class ProxmoxTestConnectionResponse(BaseModel):
+ connected: bool
+ message: str
+
+
+class ProxmoxNodeOut(BaseModel):
+ """A homelable-ready node representation of a Proxmox host / VM / LXC."""
+
+ id: str
+ label: str
+ type: str # proxmox | vm | lxc
+ ieee_address: str
+ hostname: str | None = None
+ ip: str | None = None
+ status: str
+ cpu_count: int | None = None
+ ram_gb: float | None = None
+ disk_gb: float | None = None
+ vendor: str | None = None
+ model: str | None = None
+ parent_ieee: str | None = None
+
+
+class ProxmoxEdgeOut(BaseModel):
+ source: str
+ target: str
+
+
+class ProxmoxImportResponse(BaseModel):
+ nodes: list[ProxmoxNodeOut]
+ edges: list[ProxmoxEdgeOut]
+ device_count: int
+
+
+class ProxmoxImportPendingResponse(BaseModel):
+ """Result of importing a Proxmox inventory into the pending section."""
+
+ pending_created: int
+ pending_updated: int
+ links_recorded: int
+ device_count: int
+
+
+class ProxmoxConfig(BaseModel):
+ """Non-secret Proxmox connection + auto-sync config. Never carries a token —
+ ``token_configured`` reflects whether a server-side token is present."""
+
+ host: str = ""
+ port: int = Field(8006, ge=1, le=65535)
+ verify_tls: bool = True
+ sync_enabled: bool = False
+ sync_interval: int = Field(3600, ge=300)
+ token_configured: bool = False
diff --git a/backend/app/schemas/scan.py b/backend/app/schemas/scan.py
index 3b7cef7..d64bd79 100644
--- a/backend/app/schemas/scan.py
+++ b/backend/app/schemas/scan.py
@@ -20,6 +20,9 @@ class PendingDeviceResponse(BaseModel):
model: str | None = None
vendor: str | None = None
lqi: int | None = None
+ # Display properties carried from discovery (e.g. Proxmox specs). Merged into
+ # the node on approve; empty for scan/mesh sources that don't set them.
+ properties: list[Any] = []
discovered_at: datetime
# Number of distinct canvases (designs) this device already appears on,
# correlated by ip / ieee_address against existing nodes. Computed per-request.
diff --git a/backend/app/services/proxmox_service.py b/backend/app/services/proxmox_service.py
new file mode 100644
index 0000000..423be85
--- /dev/null
+++ b/backend/app/services/proxmox_service.py
@@ -0,0 +1,348 @@
+"""Proxmox VE inventory service: fetch hosts + VMs + LXC via the PVE REST API.
+
+Mirrors the Zigbee/Z-Wave import pipeline, but talks to the Proxmox VE REST API
+(``/api2/json``) over HTTPS with an API token instead of MQTT. It returns plain
+homelable node dicts + parent→child edge hints; DB persistence lives in the
+route layer (``app.api.routes.proxmox``).
+
+Auth uses a Proxmox **API token** (never a password):
+``Authorization: PVEAPIToken=<token_id>=<secret>`` where ``token_id`` looks like
+``user@realm!tokenname``. A read-only ``PVEAuditor`` role is all that is needed.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+import httpx
+
+from app.services.zigbee_service import merge_zigbee_properties
+
+logger = logging.getLogger(__name__)
+
+# Reuse the zigbee property-merge contract verbatim (same NodeProperty shape +
+# visibility-preservation rules) for re-sync updates.
+merge_proxmox_properties = merge_zigbee_properties
+
+_CONNECT_TIMEOUT = 8.0
+_READ_TIMEOUT = 20.0
+_BYTES_PER_GB = 1024 ** 3
+
+# net0 config line: "name=eth0,bridge=vmbr0,ip=192.168.1.5/24,gw=..."
+_LXC_IP_RE = re.compile(r"(?:^|,)ip=([0-9]{1,3}(?:\.[0-9]{1,3}){3})(?:/\d+)?")
+
+
+def _sanitize_proxmox_error(exc: BaseException) -> str:
+ """Return a generic, credential-free message for a Proxmox/HTTP error.
+
+ Raw httpx errors can echo the request URL and, worse, an
+ ``Authorization: PVEAPIToken=...=<secret>`` header in some stacks. Map known
+ patterns to coarse categories so the token never reaches an API client. The
+ original exception is logged at WARNING for operators.
+ """
+ logger.warning("Proxmox error (sanitized for client): %r", exc)
+ if isinstance(exc, httpx.HTTPStatusError):
+ code = exc.response.status_code
+ if code in (401, 403):
+ return "Authentication failed — check the API token and its permissions"
+ if code == 404:
+ return "Proxmox API path not found — is this a Proxmox VE host?"
+ return f"Proxmox API returned HTTP {code}"
+ raw = str(exc).lower()
+ if "name or service not known" in raw or "getaddrinfo" in raw or "nodename nor servname" in raw:
+ return "Proxmox host could not be resolved"
+ if "refused" in raw:
+ return "Connection refused by Proxmox host"
+ if "certificate" in raw or "ssl" in raw or "tls" in raw:
+ return "TLS verification failed — enable 'skip TLS verify' for self-signed certs"
+ if "timed out" in raw or "timeout" in raw:
+ return "Connection to Proxmox host timed out"
+ return "Proxmox connection failed"
+
+
+def _auth_header(token_id: str, token_secret: str) -> dict[str, str]:
+ return {"Authorization": f"PVEAPIToken={token_id}={token_secret}"}
+
+
+def _gb(value: Any) -> float | None:
+ """Convert a byte count to GB (1 decimal). None/0 → None."""
+ try:
+ num = float(value)
+ except (TypeError, ValueError):
+ return None
+ if num <= 0:
+ return None
+ return round(num / _BYTES_PER_GB, 1)
+
+
+def _int_or_none(value: Any) -> int | None:
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _guest_type_to_homelable(kind: str) -> str:
+ """qemu → vm, lxc → lxc (both existing homelable node types)."""
+ return "vm" if kind == "qemu" else "lxc"
+
+
+def _extract_qemu_ip(agent_payload: dict[str, Any] | None) -> str | None:
+ """Pull the first non-loopback IPv4 from a qemu guest-agent interfaces reply."""
+ if not agent_payload:
+ return None
+ result = agent_payload.get("result")
+ if not isinstance(result, list):
+ return None
+ for iface in result:
+ if not isinstance(iface, dict):
+ continue
+ for addr in iface.get("ip-addresses") or []:
+ if not isinstance(addr, dict):
+ continue
+ if addr.get("ip-address-type") != "ipv4":
+ continue
+ ip = addr.get("ip-address")
+ if isinstance(ip, str) and ip and not ip.startswith("127."):
+ return ip
+ return None
+
+
+def _extract_lxc_ip(config_payload: dict[str, Any] | None) -> str | None:
+ """Parse a static IPv4 from an LXC ``net0`` config string (skip dhcp)."""
+ if not config_payload:
+ return None
+ net0 = config_payload.get("net0")
+ if not isinstance(net0, str):
+ return None
+ match = _LXC_IP_RE.search(net0)
+ return match.group(1) if match else None
+
+
+def _host_node(raw: dict[str, Any]) -> dict[str, Any] | None:
+ """Build a homelable ``proxmox`` host node from a ``/nodes`` entry."""
+ name = raw.get("node")
+ if not name:
+ return None
+ ieee = f"pve-node-{name}"
+ return {
+ "id": ieee,
+ "label": name,
+ "type": "proxmox",
+ "ieee_address": ieee,
+ "hostname": name,
+ "ip": raw.get("ip") or None,
+ "status": "online" if raw.get("status") == "online" else "offline",
+ "cpu_count": _int_or_none(raw.get("maxcpu")),
+ "ram_gb": _gb(raw.get("maxmem")),
+ "disk_gb": _gb(raw.get("maxdisk")),
+ "vendor": "Proxmox VE",
+ "model": None,
+ "parent_ieee": None,
+ }
+
+
+def _guest_node(raw: dict[str, Any], host_name: str, kind: str, ip: str | None) -> dict[str, Any] | None:
+ """Build a homelable vm/lxc node from a ``/qemu`` or ``/lxc`` list entry."""
+ vmid = raw.get("vmid")
+ if vmid is None:
+ return None
+ ieee = f"pve-{host_name}-{vmid}"
+ node_type = _guest_type_to_homelable(kind)
+ name = raw.get("name") or f"{node_type}-{vmid}"
+ return {
+ "id": ieee,
+ "label": name,
+ "type": node_type,
+ "ieee_address": ieee,
+ "hostname": name,
+ "ip": ip,
+ "status": "online" if raw.get("status") == "running" else "offline",
+ "cpu_count": _int_or_none(raw.get("maxcpu") or raw.get("cpus")),
+ "ram_gb": _gb(raw.get("maxmem")),
+ "disk_gb": _gb(raw.get("maxdisk")),
+ "vendor": "Proxmox VE",
+ "model": kind.upper(),
+ "vmid": vmid,
+ "parent_ieee": f"pve-node-{host_name}",
+ }
+
+
+def build_proxmox_properties(node: dict[str, Any]) -> list[dict[str, Any]]:
+ """Build a NodeProperty list for a Proxmox device (specs + identity).
+
+ Icons match the existing hardware-property convention (``Cpu`` /
+ ``MemoryStick`` / ``HardDrive``). All rows default ``visible=False`` — the
+ user opts in from the right panel, same as the mesh importers."""
+ props: list[dict[str, Any]] = []
+ vmid = node.get("vmid")
+ if vmid is not None:
+ props.append({"key": "VMID", "value": str(vmid), "icon": None, "visible": False})
+ if node.get("model"):
+ props.append({"key": "Kind", "value": node["model"], "icon": None, "visible": False})
+ if node.get("cpu_count") is not None:
+ props.append({"key": "CPU Cores", "value": str(node["cpu_count"]), "icon": "Cpu", "visible": False})
+ if node.get("ram_gb") is not None:
+ props.append({"key": "RAM", "value": f"{node['ram_gb']} GB", "icon": "MemoryStick", "visible": False})
+ if node.get("disk_gb") is not None:
+ props.append({"key": "Disk", "value": f"{node['disk_gb']} GB", "icon": "HardDrive", "visible": False})
+ props.append({"key": "Source", "value": "Proxmox VE", "icon": None, "visible": False})
+ return props
+
+
+def _parse_inventory(
+ hosts_raw: list[dict[str, Any]],
+ guests_by_host: dict[str, list[dict[str, Any]]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ """Assemble (nodes, edges) from fetched host + guest data.
+
+ ``guests_by_host`` maps host name → list of already-normalized guest node
+ dicts. Edges are one host→guest link per guest (materialized as canvas
+ edges on approval, mirroring the zigbee/zwave link mechanism).
+ """
+ nodes: list[dict[str, Any]] = []
+ edges: list[dict[str, Any]] = []
+ seen: set[str] = set()
+
+ for raw in hosts_raw:
+ host = _host_node(raw)
+ if host is None or host["id"] in seen:
+ continue
+ seen.add(host["id"])
+ nodes.append(host)
+
+ for host_name, guests in guests_by_host.items():
+ host_ieee = f"pve-node-{host_name}"
+ for guest in guests:
+ if guest["id"] in seen:
+ continue
+ seen.add(guest["id"])
+ nodes.append(guest)
+ edges.append({"source": host_ieee, "target": guest["id"]})
+
+ return nodes, edges
+
+
+async def _get_json(client: httpx.AsyncClient, path: str) -> Any:
+ resp = await client.get(path)
+ resp.raise_for_status()
+ return resp.json().get("data")
+
+
+async def fetch_proxmox_inventory(
+ host: str,
+ port: int,
+ token_id: str,
+ token_secret: str,
+ verify_tls: bool = True,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ """Fetch hosts + VMs + LXC from a Proxmox VE host, return (nodes, edges).
+
+ Raises:
+ ConnectionError: transport/DNS/TLS failures (sanitized message).
+ ValueError: malformed API response.
+ """
+ base_url = f"https://{host}:{port}/api2/json"
+ timeout = httpx.Timeout(_READ_TIMEOUT, connect=_CONNECT_TIMEOUT)
+ guests_by_host: dict[str, list[dict[str, Any]]] = {}
+
+ try:
+ async with httpx.AsyncClient(
+ base_url=base_url,
+ headers=_auth_header(token_id, token_secret),
+ verify=verify_tls,
+ timeout=timeout,
+ ) as client:
+ hosts_raw = await _get_json(client, "/nodes")
+ if not isinstance(hosts_raw, list):
+ raise ValueError("Malformed /nodes response")
+
+ for host_entry in hosts_raw:
+ name = host_entry.get("node")
+ if not name or host_entry.get("status") != "online":
+ # Offline nodes can't be queried for guests; still shown as host.
+ continue
+ guests_by_host[name] = await _fetch_host_guests(client, name)
+ except httpx.HTTPStatusError as exc:
+ raise ConnectionError(_sanitize_proxmox_error(exc)) from exc
+ except httpx.HTTPError as exc:
+ raise ConnectionError(_sanitize_proxmox_error(exc)) from exc
+
+ return _parse_inventory(hosts_raw, guests_by_host)
+
+
+async def _fetch_host_guests(
+ client: httpx.AsyncClient, host_name: str
+) -> list[dict[str, Any]]:
+ """Fetch qemu + lxc guests for one host, resolving guest IPs best-effort."""
+ guests: list[dict[str, Any]] = []
+
+ for kind in ("qemu", "lxc"):
+ try:
+ entries = await _get_json(client, f"/nodes/{host_name}/{kind}")
+ except httpx.HTTPError as exc:
+ logger.warning("Proxmox %s list failed for %s: %s", kind, host_name, exc)
+ continue
+ if not isinstance(entries, list):
+ continue
+ for raw in entries:
+ ip = await _resolve_guest_ip(client, host_name, kind, raw)
+ node = _guest_node(raw, host_name, kind, ip)
+ if node:
+ guests.append(node)
+
+ return guests
+
+
+async def _resolve_guest_ip(
+ client: httpx.AsyncClient, host_name: str, kind: str, raw: dict[str, Any]
+) -> str | None:
+ """Best-effort guest IP. qemu → guest agent, lxc → net0 config. Never raises."""
+ vmid = raw.get("vmid")
+ if vmid is None:
+ return None
+ try:
+ if kind == "qemu":
+ if raw.get("status") != "running":
+ return None
+ data = await _get_json(
+ client, f"/nodes/{host_name}/qemu/{vmid}/agent/network-get-interfaces"
+ )
+ return _extract_qemu_ip(data)
+ data = await _get_json(client, f"/nodes/{host_name}/lxc/{vmid}/config")
+ return _extract_lxc_ip(data)
+ except httpx.HTTPError:
+ # Guest agent not installed / container stopped / no perms → no IP. Fine.
+ return None
+
+
+async def test_proxmox_connection(
+ host: str,
+ port: int,
+ token_id: str,
+ token_secret: str,
+ verify_tls: bool = True,
+) -> tuple[bool, str]:
+ """Quick reachability + auth check via ``GET /version``.
+
+ Returns (connected, message). Never raises credentials outward.
+ """
+ base_url = f"https://{host}:{port}/api2/json"
+ timeout = httpx.Timeout(_READ_TIMEOUT, connect=_CONNECT_TIMEOUT)
+ try:
+ async with httpx.AsyncClient(
+ base_url=base_url,
+ headers=_auth_header(token_id, token_secret),
+ verify=verify_tls,
+ timeout=timeout,
+ ) as client:
+ data = await _get_json(client, "/version")
+ version = (data or {}).get("version", "?") if isinstance(data, dict) else "?"
+ return True, f"Connected to Proxmox VE {version}"
+ except httpx.HTTPError as exc:
+ return False, _sanitize_proxmox_error(exc)
+ except Exception as exc: # noqa: BLE001 — surface a safe message, log the rest
+ logger.exception("Unexpected error during Proxmox connection test")
+ return False, _sanitize_proxmox_error(exc)
diff --git a/backend/tests/test_proxmox_router.py b/backend/tests/test_proxmox_router.py
new file mode 100644
index 0000000..2303430
--- /dev/null
+++ b/backend/tests/test_proxmox_router.py
@@ -0,0 +1,188 @@
+"""API + persistence tests for /api/v1/proxmox/*."""
+
+from __future__ import annotations
+
+import uuid
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.api.routes.proxmox import _persist_pending_import
+from app.core.config import settings
+from app.db.models import Node, PendingDevice
+
+
+async def headers(client: AsyncClient):
+ res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
+ token = res.json()["access_token"]
+ return {"Authorization": f"Bearer {token}"}
+
+
[email protected](autouse=True)
+def _clear_env_token():
+ """Ensure a clean token state per test; restore afterwards."""
+ tid, sec = settings.proxmox_token_id, settings.proxmox_token_secret
+ settings.proxmox_token_id = ""
+ settings.proxmox_token_secret = ""
+ yield
+ settings.proxmox_token_id, settings.proxmox_token_secret = tid, sec
+
+
+def _host_node() -> dict:
+ return {
+ "id": "pve-node-pve1", "label": "pve1", "type": "proxmox",
+ "ieee_address": "pve-node-pve1", "hostname": "pve1", "ip": None,
+ "status": "online", "cpu_count": 8, "ram_gb": 16.0, "disk_gb": 500.0,
+ "vendor": "Proxmox VE", "model": None, "parent_ieee": None,
+ }
+
+
+def _guest_node(vmid: int, ip: str | None, status: str = "online") -> dict:
+ return {
+ "id": f"pve-pve1-{vmid}", "label": f"vm{vmid}", "type": "vm",
+ "ieee_address": f"pve-pve1-{vmid}", "hostname": f"vm{vmid}", "ip": ip,
+ "status": status, "cpu_count": 2, "ram_gb": 4.0, "disk_gb": 32.0,
+ "vendor": "Proxmox VE", "model": "QEMU", "vmid": vmid,
+ "parent_ieee": "pve-node-pve1",
+ }
+
+
+# --- endpoints -------------------------------------------------------------
+
+async def test_test_connection_uses_body_token(client: AsyncClient, headers: dict) -> None:
+ with patch("app.api.routes.proxmox.test_proxmox_connection", new=AsyncMock(return_value=(True, "ok"))):
+ res = await client.post(
+ "/api/v1/proxmox/test-connection",
+ json={"host": "pve", "port": 8006, "token_id": "u@pam!t", "token_secret": "s"},
+ headers=headers,
+ )
+ assert res.status_code == 200
+ assert res.json()["connected"] is True
+
+
+async def test_missing_token_is_rejected(client: AsyncClient, headers: dict) -> None:
+ res = await client.post(
+ "/api/v1/proxmox/test-connection",
+ json={"host": "pve", "port": 8006},
+ headers=headers,
+ )
+ assert res.status_code == 400
+
+
+async def test_import_pending_creates_scan_run(client: AsyncClient, headers: dict) -> None:
+ with patch("app.api.routes.proxmox._background_proxmox_import", new_callable=AsyncMock):
+ res = await client.post(
+ "/api/v1/proxmox/import-pending",
+ json={"host": "pve", "port": 8006, "token_id": "u@pam!t", "token_secret": "s"},
+ headers=headers,
+ )
+ assert res.status_code == 200
+ data = res.json()
+ assert data["kind"] == "proxmox"
+ assert data["status"] == "running"
+
+
+async def test_requires_auth(client: AsyncClient) -> None:
+ res = await client.post("/api/v1/proxmox/import-pending", json={"host": "pve"})
+ assert res.status_code == 401
+
+
+async def test_config_omits_token(client: AsyncClient, headers: dict) -> None:
+ settings.proxmox_token_id = "u@pam!t"
+ settings.proxmox_token_secret = "supersecret"
+ res = await client.get("/api/v1/proxmox/config", headers=headers)
+ assert res.status_code == 200
+ body = res.text
+ assert "supersecret" not in body
+ assert res.json()["token_configured"] is True
+
+
+async def test_enable_sync_without_token_rejected(client: AsyncClient, headers: dict) -> None:
+ res = await client.post(
+ "/api/v1/proxmox/config",
+ json={"host": "pve", "port": 8006, "verify_tls": True, "sync_enabled": True, "sync_interval": 600},
+ headers=headers,
+ )
+ assert res.status_code == 400
+
+
+# --- persistence / dedupe --------------------------------------------------
+
+async def test_persist_creates_pending(db_session) -> None:
+ nodes = [_host_node(), _guest_node(101, "10.0.0.5")]
+ edges = [{"source": "pve-node-pve1", "target": "pve-pve1-101"}]
+ result = await _persist_pending_import(db_session, nodes, edges)
+ assert result.pending_created == 2
+ assert result.links_recorded == 1
+ rows = (await db_session.execute(select(PendingDevice))).scalars().all()
+ assert {r.suggested_type for r in rows} == {"proxmox", "vm"}
+ # Specs carried as properties.
+ vm = next(r for r in rows if r.suggested_type == "vm")
+ assert any(p["key"] == "CPU Cores" for p in vm.properties)
+
+
+async def test_persist_merges_existing_scanned_node_by_ip(db_session) -> None:
+ # A device previously found by an IP scan (no ieee, no specs).
+ scanned = Node(
+ id=str(uuid.uuid4()), type="generic", label="10.0.0.5",
+ ip="10.0.0.5", status="online", pos_x=0, pos_y=0,
+ )
+ db_session.add(scanned)
+ await db_session.commit()
+
+ await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.5")], [])
+
+ # No duplicate node; identity + specs merged onto the existing one.
+ nodes = (await db_session.execute(select(Node).where(Node.ip == "10.0.0.5"))).scalars().all()
+ assert len(nodes) == 1
+ merged = nodes[0]
+ assert merged.ieee_address == "pve-pve1-101"
+ assert merged.cpu_count == 2
+ assert any(p["key"] == "CPU Cores" for p in (merged.properties or []))
+ # Inventory row exists as approved (already on canvas).
+ inv = (await db_session.execute(select(PendingDevice).where(PendingDevice.ieee_address == "pve-pve1-101"))).scalar_one()
+ assert inv.status == "approved"
+
+
+async def test_persist_resync_updates_in_place(db_session) -> None:
+ nodes = [_guest_node(101, "10.0.0.5")]
+ await _persist_pending_import(db_session, nodes, [])
+ # Second sync: same device, new IP. Should update, not duplicate.
+ await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.9")], [])
+ rows = (await db_session.execute(select(PendingDevice).where(PendingDevice.ieee_address == "pve-pve1-101"))).scalars().all()
+ assert len(rows) == 1
+ assert rows[0].ip == "10.0.0.9"
+
+
+async def test_persist_keeps_hidden_hidden(db_session) -> None:
+ db_session.add(PendingDevice(
+ id=str(uuid.uuid4()), ieee_address="pve-pve1-101", ip="10.0.0.5",
+ suggested_type="vm", status="hidden", discovery_source="proxmox",
+ ))
+ await db_session.commit()
+ await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.5")], [])
+ row = (await db_session.execute(select(PendingDevice).where(PendingDevice.ieee_address == "pve-pve1-101"))).scalar_one()
+ assert row.status == "hidden"
+
+
+async def test_persist_never_deletes(db_session) -> None:
+ await _persist_pending_import(db_session, [_guest_node(101, "10.0.0.5")], [])
+ # A later sync that no longer includes vm101 must not remove it.
+ await _persist_pending_import(db_session, [_guest_node(202, "10.0.0.6")], [])
+ rows = (await db_session.execute(select(PendingDevice))).scalars().all()
+ ieees = {r.ieee_address for r in rows}
+ assert "pve-pve1-101" in ieees and "pve-pve1-202" in ieees
diff --git a/backend/tests/test_proxmox_service.py b/backend/tests/test_proxmox_service.py
new file mode 100644
index 0000000..ca2913e
--- /dev/null
+++ b/backend/tests/test_proxmox_service.py
@@ -0,0 +1,123 @@
+"""Unit tests for the Proxmox VE import service (parsing, props, sanitizer)."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+
+from app.services import proxmox_service as svc
+
+
+def test_gb_conversion() -> None:
+ assert svc._gb(1024 ** 3) == 1.0
+ assert svc._gb(2 * 1024 ** 3) == 2.0
+ assert svc._gb(0) is None
+ assert svc._gb(None) is None
+ assert svc._gb("nope") is None
+
+
+def test_extract_qemu_ip_skips_loopback() -> None:
+ payload = {
+ "result": [
+ {"name": "lo", "ip-addresses": [{"ip-address-type": "ipv4", "ip-address": "127.0.0.1"}]},
+ {"name": "eth0", "ip-addresses": [{"ip-address-type": "ipv4", "ip-address": "192.168.1.20"}]},
+ ]
+ }
+ assert svc._extract_qemu_ip(payload) == "192.168.1.20"
+ assert svc._extract_qemu_ip(None) is None
+ assert svc._extract_qemu_ip({"result": []}) is None
+
+
+def test_extract_lxc_ip_parses_net0_static() -> None:
+ cfg = {"net0": "name=eth0,bridge=vmbr0,ip=192.168.1.30/24,gw=192.168.1.1"}
+ assert svc._extract_lxc_ip(cfg) == "192.168.1.30"
+ # DHCP → no static IP
+ assert svc._extract_lxc_ip({"net0": "name=eth0,bridge=vmbr0,ip=dhcp"}) is None
+ assert svc._extract_lxc_ip(None) is None
+
+
+def test_host_and_guest_node_mapping() -> None:
+ host = svc._host_node({"node": "pve1", "status": "online", "maxcpu": 8, "maxmem": 16 * 1024 ** 3, "maxdisk": 500 * 1024 ** 3})
+ assert host["type"] == "proxmox"
+ assert host["ieee_address"] == "pve-node-pve1"
+ assert host["cpu_count"] == 8
+ assert host["ram_gb"] == 16.0
+ assert host["status"] == "online"
+ assert host["parent_ieee"] is None
+
+ vm = svc._guest_node({"vmid": 101, "name": "web", "status": "running", "maxcpu": 2, "maxmem": 2 * 1024 ** 3, "maxdisk": 32 * 1024 ** 3}, "pve1", "qemu", "10.0.0.5")
+ assert vm["type"] == "vm"
+ assert vm["ieee_address"] == "pve-pve1-101"
+ assert vm["ip"] == "10.0.0.5"
+ assert vm["status"] == "online"
+ assert vm["parent_ieee"] == "pve-node-pve1"
+
+ ct = svc._guest_node({"vmid": 200, "name": "db", "status": "stopped"}, "pve1", "lxc", None)
+ assert ct["type"] == "lxc"
+ assert ct["status"] == "offline"
+
+
+def test_build_properties_includes_specs() -> None:
+ node = {"vmid": 101, "model": "QEMU", "cpu_count": 4, "ram_gb": 8.0, "disk_gb": 40.0}
+ props = svc.build_proxmox_properties(node)
+ keys = {p["key"] for p in props}
+ assert {"VMID", "CPU Cores", "RAM", "Disk", "Source"} <= keys
+ assert all(p["visible"] is False for p in props)
+
+
+def test_parse_inventory_builds_host_guest_edges() -> None:
+ hosts = [{"node": "pve1", "status": "online", "maxcpu": 4}]
+ guests = {"pve1": [svc._guest_node({"vmid": 101, "name": "web", "status": "running"}, "pve1", "qemu", None)]}
+ nodes, edges = svc._parse_inventory(hosts, guests)
+ assert len(nodes) == 2
+ assert edges == [{"source": "pve-node-pve1", "target": "pve-pve1-101"}]
+
+
+def test_sanitize_error_hides_credentials() -> None:
+ exc = httpx.HTTPStatusError(
+ "boom", request=httpx.Request("GET", "https://h/api2/json"),
+ response=httpx.Response(401),
+ )
+ msg = svc._sanitize_proxmox_error(exc)
+ assert "token" not in msg.lower() or "check the api token" in msg.lower()
+ assert "Authentication failed" in msg
+
+
+async def test_fetch_inventory_happy_path() -> None:
+ async def fake_get_json(client, path: str):
+ if path == "/nodes":
+ return [{"node": "pve1", "status": "online", "maxcpu": 8, "maxmem": 16 * 1024 ** 3}]
+ if path == "/nodes/pve1/qemu":
+ return [{"vmid": 101, "name": "web", "status": "running", "maxmem": 2 * 1024 ** 3}]
+ if path == "/nodes/pve1/lxc":
+ return [{"vmid": 200, "name": "db", "status": "stopped"}]
+ if path.endswith("/agent/network-get-interfaces"):
+ return {"result": [{"name": "eth0", "ip-addresses": [{"ip-address-type": "ipv4", "ip-address": "10.0.0.5"}]}]}
+ if path.endswith("/config"):
+ return {"net0": "name=eth0,ip=10.0.0.6/24"}
+ return None
+
+ with patch.object(svc, "_get_json", new=AsyncMock(side_effect=fake_get_json)):
+ nodes, edges = await svc.fetch_proxmox_inventory("h", 8006, "u@pam!t", "sec")
+
+ by_type = {n["type"] for n in nodes}
+ assert by_type == {"proxmox", "vm", "lxc"}
+ vm = next(n for n in nodes if n["type"] == "vm")
+ assert vm["ip"] == "10.0.0.5"
+ ct = next(n for n in nodes if n["type"] == "lxc")
+ assert ct["ip"] == "10.0.0.6"
+ assert len(edges) == 2
+
+
+async def test_test_connection_returns_message() -> None:
+ async def fake_get_json(client, path: str):
+ return {"version": "8.2.2"}
+
+ with patch.object(svc, "_get_json", new=AsyncMock(side_effect=fake_get_json)):
+ ok, msg = await svc.test_proxmox_connection("h", 8006, "u@pam!t", "sec")
+ assert ok is True
+ assert "8.2.2" in msg
diff --git a/backend/tests/test_scheduler.py b/backend/tests/test_scheduler.py
index 078ea1a..12eb8a5 100644
--- a/backend/tests/test_scheduler.py
+++ b/backend/tests/test_scheduler.py
@@ -6,8 +6,11 @@ import pytest
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from app.core.scheduler import (
+ _run_proxmox_sync,
_run_service_checks,
_run_status_checks,
+ reschedule_proxmox_sync,
+ set_proxmox_sync_enabled,
set_service_checks_enabled,
start_scheduler,
stop_scheduler,
@@ -148,6 +151,7 @@ def test_scheduler_uses_settings_interval():
patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched):
mock_settings.status_checker_interval = 45
mock_settings.service_check_enabled = False
+ mock_settings.proxmox_sync_enabled = False
start_scheduler()
_, kwargs = mock_sched.add_job.call_args
assert kwargs["seconds"] == 45
@@ -156,7 +160,11 @@ def test_scheduler_uses_settings_interval():
def test_start_and_stop_scheduler():
"""Scheduler can be started and stopped without errors."""
mock_sched = MagicMock()
- with patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched):
+ with patch("app.core.scheduler.AsyncIOScheduler", return_value=mock_sched), \
+ patch("app.core.scheduler.settings") as mock_settings:
+ mock_settings.status_checker_interval = 60
+ mock_settings.service_check_enabled = False
+ mock_settings.proxmox_sync_enabled = False
start_scheduler()
stop_scheduler()
mock_sched.add_job.assert_called_once()
@@ -245,7 +253,49 @@ def test_start_scheduler_adds_service_job_when_enabled():
mock_settings.status_checker_interval = 60
mock_settings.service_check_enabled = True
mock_settings.service_check_interval = 300
+ mock_settings.proxmox_sync_enabled = False
start_scheduler()
job_ids = [kw.get("id") for _, kw in mock_sched.add_job.call_args_list]
assert "status_checks" in job_ids
assert "service_checks" in job_ids
+
+
+# ---------------------------------------------------------------------------
+# Proxmox auto-sync job
+# ---------------------------------------------------------------------------
+
+def test_set_proxmox_sync_enabled_adds_and_removes_job():
+ mock_sched = MagicMock()
+ mock_sched.running = True
+ with patch("app.core.scheduler.scheduler", mock_sched), \
+ patch("app.core.scheduler.settings") as mock_settings:
+ mock_settings.proxmox_sync_interval = 3600
+ mock_sched.get_job.return_value = None
+ set_proxmox_sync_enabled(True)
+ mock_sched.add_job.assert_called_once()
+ mock_sched.get_job.return_value = MagicMock()
+ set_proxmox_sync_enabled(False)
+ mock_sched.remove_job.assert_called_once_with("proxmox_sync")
+
+
+def test_reschedule_proxmox_sync_rejects_short_interval():
+ with pytest.raises(ValueError):
+ reschedule_proxmox_sync(60)
+
+
+async def test_run_proxmox_sync_skips_when_disabled():
+ with patch("app.core.scheduler.settings") as mock_settings:
+ mock_settings.proxmox_sync_enabled = False
+ # Must return before importing/fetching anything.
+ await _run_proxmox_sync()
+
+
+async def test_run_proxmox_sync_skips_when_no_token():
+ with patch("app.core.scheduler.settings") as mock_settings:
+ mock_settings.proxmox_sync_enabled = True
+ mock_settings.proxmox_host = "pve"
+ mock_settings.proxmox_token_id = ""
+ mock_settings.proxmox_token_secret = ""
+ await _run_proxmox_sync() # no exception, no fetch
diff --git a/docs/proxmox-import.md b/docs/proxmox-import.md
new file mode 100644
index 0000000..25d9146
--- /dev/null
+++ b/docs/proxmox-import.md
@@ -0,0 +1,188 @@
+# Proxmox VE Import
+
+This feature connects Homelable to your Proxmox VE host, reads the inventory over
+the Proxmox REST API, and drops your hosts, VMs and LXC containers onto the canvas
+as typed nodes — with names, run state and hardware specs. It can also **sync**
+on a schedule so the canvas keeps up with your cluster, and it **merges** with
+devices already discovered by a network scan (a VM whose guest IP was already
+scanned is updated in place, not duplicated).
+
+> 🔒 **Server-dependent feature** — requires the Homelable backend. It is hidden
+> in the no-backend standalone/demo build.
+
+---
+
+## Feature Overview
+
+- **API-based discovery** — Reads `/api2/json` from Proxmox VE using a read-only API token.
+- **Typed nodes** — Devices map to existing Homelable node types:
+ - `proxmox` — a Proxmox host / cluster member (becomes a parent)
+ - `vm` — a QEMU/KVM virtual machine
+ - `lxc` — an LXC container
+- **Hierarchy** — Each host is linked to its VMs/LXC with a `virtual` edge.
+- **Hardware specs** — vCPU count, RAM and disk size are imported as node properties (CPU Cores, RAM, Disk), hidden by default — toggle them on from the right panel.
+- **Guest IPs** — QEMU IPs come from the guest agent (when installed); LXC IPs are parsed from the container's static `net0` config.
+- **Merge / sync** — Re-importing updates existing devices in place and never deletes anything. A guest IP matching a previously scanned node merges onto it.
+- **Auto-sync** — Optional scheduled re-import into the pending inventory.
+
+---
+
+## Prerequisites
+
+1. A reachable **Proxmox VE** host (default API port `8006`).
+2. A **Proxmox API token** with a read-only role (see below).
+3. (Optional, for QEMU guest IPs) the **QEMU guest agent** installed in your VMs.
+
+### Create an API token
+
+In the Proxmox web UI:
+
+1. **Datacenter → Permissions → API Tokens → Add**.
+2. Pick a **User** (e.g. `root@pam`, or better a dedicated `homelable@pve` user).
+3. Give the token an **ID** (e.g. `homelable`). The full token id is then
+ `user@realm!tokenid` — for example `root@pam!homelable`.
+4. Leave **Privilege Separation** checked (recommended) and click **Add**.
+5. **Copy the secret now** — Proxmox shows it only once.
+
+Grant the token (or its user) a **read-only** role:
+
+1. **Datacenter → Permissions → Add → API Token Permission**.
+2. Path `/`, select your token, Role **`PVEAuditor`**, enable **Propagate**.
+
+`PVEAuditor` is read-only — Homelable never needs write access.
+
+### Where the token is stored
+
+The token is a real credential and is treated as one:
+
+- For a **one-off import**, type the token into the import dialog. It is sent with
+ that request only and is **never stored**.
+- For **auto-sync** (which runs with no user present), configure the token on the
+ **server** via environment variables (below). It is read from `.env`, kept in
+ memory, **never written to disk by the app**, and **never returned by any API**
+ endpoint. Connection errors are sanitized so the token can't leak in a message.
+
+```env
+# backend/.env
+PROXMOX_TOKEN_ID=root@pam!homelable
+PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+PROXMOX_HOST=192.168.1.10 # optional default for auto-sync
+PROXMOX_PORT=8006
+PROXMOX_VERIFY_TLS=true # set false only for self-signed certs
+```
+
+---
+
+## Step-by-step Usage
+
+### 1. Open the Proxmox Import dialog
+
+Click **Proxmox Import** in the left sidebar (below "Z-Wave Import").
+
+### 2. Configure the connection
+
+| Field | Default | Description |
+|---|---|---|
+| Proxmox Host | — | IP or hostname of the Proxmox host |
+| Port | 8006 | Proxmox API port |
+| Token ID | _(optional)_ | `user@realm!tokenid`; leave blank to use the server token |
+| Token Secret | _(optional)_ | The token secret; leave blank to use the server token |
+| Verify TLS | on | Uncheck for self-signed certificates |
+
+### 3. Test the connection (optional)
+
+Click **Test Connection**. A green indicator confirms reachability + a valid token;
+red shows a sanitized error.
+
+### 4. Choose an import target
+
+- **Pending section** — Devices are queued in the Device Inventory for review
+ (and tracked as a scan run in Scan History). Approve, hide, or delete each.
+- **Canvas directly** — Devices are fetched and shown grouped in the dialog so you
+ can pick which ones to add immediately.
+
+### 5. Fetch inventory
+
+Click **Import to Pending** (or **Fetch Inventory** in canvas mode). Homelable will:
+1. Query `/nodes` for hosts
+2. Query `/qemu` and `/lxc` per host
+3. Resolve guest IPs (agent for QEMU, `net0` for LXC) best-effort
+4. Return hosts + guests grouped by type
+
+### 6. Select and add to canvas
+
+(Canvas mode) Devices are grouped by type (Hosts / Virtual Machines / LXC
+Containers). Use the checkboxes to pick which to add, then **Add N to Canvas**.
+
+### 7. Arrange on the canvas
+
+Nodes are placed in a grid; host→guest `virtual` edges connect them. Use
+**Auto Layout** or drag nodes manually.
+
+---
+
+## Node Type Mapping
+
+| Proxmox (`/api2/json`) | Homelable type | Notes |
+|---|---|---|
+| `/nodes` (host) | `proxmox` | Becomes the parent, linked to its guests |
+| `/nodes/{node}/qemu/{vmid}` | `vm` | Guest-agent IP when available |
+| `/nodes/{node}/lxc/{vmid}` | `lxc` | Static `net0` IP when set |
+| `status` running/stopped | node status online/offline | |
+| `maxcpu` | CPU Cores property | hidden by default |
+| `maxmem` | RAM property (GB) | hidden by default |
+| `maxdisk` | Disk property (GB) | hidden by default |
+| VMID + host | synthetic identity (`pve-{host}-{vmid}`) | stable across re-imports |
+
+Guest hierarchy is rendered as `virtual` edges (host ↔ VM/LXC).
+
+---
+
+## Auto-sync configuration
+
+1. Configure `PROXMOX_TOKEN_ID` / `PROXMOX_TOKEN_SECRET` (and optionally
+ `PROXMOX_HOST`) in `backend/.env` and restart the backend.
+2. Open **Settings** — a **Proxmox auto-sync** section appears once a server token
+ is configured.
+3. Toggle **Auto-sync Proxmox inventory** and set the interval (min 300 s).
+
+On each run, Homelable re-imports the inventory into the pending section:
+- New VMs/LXC appear as **pending** for review.
+- Existing devices are **updated in place** (status, specs, IP).
+- Nothing is ever deleted — a VM removed from Proxmox is left on your canvas.
+
+---
+
+## Security notes
+
+- Use a dedicated user + token with the read-only **`PVEAuditor`** role.
+- The token is **never** persisted to disk by Homelable and **never** included in
+ any API response; only a boolean "token configured" flag is exposed.
+- Keep `PROXMOX_VERIFY_TLS=true` in production; disable only for self-signed labs.
+- Error messages are sanitized so credentials cannot leak.
+
+---
+
+## Supported Versions
+
+Works with the Proxmox VE 7.x / 8.x REST API (`/api2/json`). No extra Proxmox
+plugins are required.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "Authentication failed" | Bad token id/secret or missing role | Re-check the token; grant `PVEAuditor` at `/` |
+| "TLS verification failed" | Self-signed certificate | Uncheck **Verify TLS** (labs only) |
+| "Proxmox host could not be resolved" | DNS/hostname wrong | Use the IP or a resolvable name |
+| "No API token provided and none configured" | No token in the form and none in `.env` | Enter a token or set the server env vars |
+| VMs have no IP | No guest agent (QEMU) / DHCP-only LXC | Install the QEMU guest agent; static IPs are read from `net0` |
+| Duplicate-looking node | Same guest under a different identity | Re-import merges by IP/VMID; report if it persists |
+
+---
+
+## Screenshots
+
+_(Screenshots will be added in a future release)_
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 925e99f..b157aac 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -25,6 +25,7 @@ import { ScanConfigModal } from '@/components/modals/ScanConfigModal'
import { SettingsModal } from '@/components/modals/SettingsModal'
import { ZigbeeImportModal } from '@/components/zigbee/ZigbeeImportModal'
import { ZwaveImportModal } from '@/components/zwave/ZwaveImportModal'
+import { ProxmoxImportModal } from '@/components/proxmox/ProxmoxImportModal'
import { GroupRectModal, type GroupRectFormData } from '@/components/modals/GroupRectModal'
import { TextModal, type TextFormData } from '@/components/modals/TextModal'
import { ThemeModal } from '@/components/modals/ThemeModal'
@@ -45,6 +46,7 @@ import { useStatusPolling } from '@/hooks/useStatusPolling'
import type { NodeData, EdgeData, CustomStyleDef, FloorMapConfig, NodeType } from '@/types'
import type { ZigbeeNode, ZigbeeEdge } from '@/components/zigbee/types'
import type { ZwaveNode, ZwaveEdge } from '@/components/zwave/types'
+import type { ProxmoxNode, ProxmoxEdge } from '@/components/proxmox/types'
const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'
@@ -84,6 +86,7 @@ export default function App() {
const [exportModalOpen, setExportModalOpen] = useState(false)
const [zigbeeImportOpen, setZigbeeImportOpen] = useState(false)
const [zwaveImportOpen, setZwaveImportOpen] = useState(false)
+ const [proxmoxImportOpen, setProxmoxImportOpen] = useState(false)
// Declare handleSave before the Ctrl+S effect so it is in scope.
// Returns true on success, false on failure — the design-switch effect relies
@@ -639,6 +642,52 @@ export default function App() {
markUnsaved()
}, [addNode, onConnect, snapshotHistory, markUnsaved])
+ const handleProxmoxAddToCanvas = useCallback((pmNodes: ProxmoxNode[], pmEdges: ProxmoxEdge[]) => {
+ snapshotHistory()
+ const COLS = 4
+ const SPACING_X = 190
+ const SPACING_Y = 110
+ const cols = Math.min(COLS, pmNodes.length)
+ const rows = Math.ceil(pmNodes.length / COLS)
+ const origin = getCenteredPosition(cols * SPACING_X, rows * SPACING_Y)
+ pmNodes.forEach((pn, i) => {
+ const col = i % COLS
+ const row = Math.floor(i / COLS)
+ const position = { x: origin.x + col * SPACING_X, y: origin.y + row * SPACING_Y }
+ const newNode: import('@xyflow/react').Node<NodeData> = {
+ id: pn.id,
+ type: pn.type,
+ position,
+ data: {
+ label: pn.label,
+ type: pn.type as NodeData['type'],
+ status: (pn.status === 'online' ? 'online' : 'unknown') as NodeData['status'],
+ services: [],
+ ...(pn.ip ? { ip: pn.ip } : {}),
+ ...(pn.hostname ? { hostname: pn.hostname } : {}),
+ },
+ }
+ addNode(newNode)
+ })
+ // Host → guest links render as 'virtual' edges (VM/LXC ↔ host).
+ pmEdges.forEach((pe) => {
+ onConnect({
+ source: pe.source,
+ sourceHandle: 'bottom',
+ target: pe.target,
+ targetHandle: 'top-t',
+ type: 'virtual',
+ } as unknown as import('@xyflow/react').Connection)
+ })
+ const importedIds = new Set(pmNodes.map((pn) => pn.id))
+ useCanvasStore.setState((state) => ({
+ nodes: state.nodes.map((n) => ({ ...n, selected: importedIds.has(n.id) })),
+ selectedNodeIds: Array.from(importedIds),
+ selectedNodeId: importedIds.size === 1 ? Array.from(importedIds)[0] : null,
+ }))
+ markUnsaved()
+ }, [addNode, onConnect, snapshotHistory, markUnsaved])
+
const handleEdgeConnect = useCallback((connection: Connection) => {
setPendingConnection(connection)
}, [])
@@ -714,6 +763,7 @@ export default function App() {
onScan={() => setScanConfigOpen(true)}
onZigbeeImport={() => setZigbeeImportOpen(true)}
onZwaveImport={() => setZwaveImportOpen(true)}
+ onProxmoxImport={() => setProxmoxImportOpen(true)}
onSave={handleSave}
onOpenSettings={() => setSettingsOpen(true)}
onOpenHistory={() => setScanHistoryOpen(true)}
@@ -840,6 +890,17 @@ export default function App() {
/>
)}
+ {!STANDALONE && (
+ <ProxmoxImportModal
+ open={proxmoxImportOpen}
+ onClose={() => setProxmoxImportOpen(false)}
+ onAddToCanvas={handleProxmoxAddToCanvas}
+ onPendingImported={() => {
+ toast.success('Proxmox import started — check Scan History for results')
+ }}
+ />
+ )}
+
{!STANDALONE && (
<ScanHistoryModal
open={scanHistoryOpen}
diff --git a/frontend/src/api/__tests__/client.test.ts b/frontend/src/api/__tests__/client.test.ts
index 557c56d..53d266e 100644
--- a/frontend/src/api/__tests__/client.test.ts
+++ b/frontend/src/api/__tests__/client.test.ts
@@ -229,4 +229,22 @@ describe('api/client', () => {
mod.zwaveApi.importToPending(cfg)
expect(api.post).toHaveBeenCalledWith('/zwave/import-pending', cfg)
})
+
+ it('proxmoxApi.testConnection/importNetwork/importToPending', () => {
+ const cfg = { host: 'pve', port: 8006, token_id: 'u@pam!t', token_secret: 's', verify_tls: true }
+ mod.proxmoxApi.testConnection(cfg)
+ expect(api.post).toHaveBeenCalledWith('/proxmox/test-connection', cfg)
+ mod.proxmoxApi.importNetwork(cfg)
+ expect(api.post).toHaveBeenCalledWith('/proxmox/import', cfg)
+ mod.proxmoxApi.importToPending(cfg)
+ expect(api.post).toHaveBeenCalledWith('/proxmox/import-pending', cfg)
+ })
+
+ it('proxmoxApi.getConfig/saveConfig hit /proxmox/config', () => {
+ mod.proxmoxApi.getConfig()
+ expect(api.get).toHaveBeenCalledWith('/proxmox/config')
+ const conf = { host: 'pve', port: 8006, verify_tls: true, sync_enabled: false, sync_interval: 3600 }
+ mod.proxmoxApi.saveConfig(conf)
+ expect(api.post).toHaveBeenCalledWith('/proxmox/config', conf)
+ })
})
diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts
index c063313..3c0aecb 100644
--- a/frontend/src/api/client.ts
+++ b/frontend/src/api/client.ts
@@ -120,6 +120,51 @@ export const settingsApi = {
save: (data: AppSettings) => api.post<AppSettings>('/settings', data),
}
+export interface ProxmoxConnection {
+ host: string
+ port: number
+ token_id?: string
+ token_secret?: string
+ verify_tls?: boolean
+}
+
+export interface ProxmoxConfigData {
+ host: string
+ port: number
+ verify_tls: boolean
+ sync_enabled: boolean
+ sync_interval: number
+ token_configured: boolean
+}
+
+export const proxmoxApi = {
+ testConnection: (data: ProxmoxConnection) =>
+ api.post<{ connected: boolean; message: string }>('/proxmox/test-connection', data),
+
+ importNetwork: (data: ProxmoxConnection) =>
+ api.post<{
+ nodes: import('@/components/proxmox/types').ProxmoxNode[]
+ edges: import('@/components/proxmox/types').ProxmoxEdge[]
+ device_count: number
+ }>('/proxmox/import', data),
+
+ importToPending: (data: ProxmoxConnection) =>
+ api.post<{
+ id: string
+ status: string
+ kind: string
+ ranges: string[]
+ devices_found: number
+ started_at: string
+ finished_at: string | null
+ error: string | null
+ }>('/proxmox/import-pending', data),
+
+ getConfig: () => api.get<ProxmoxConfigData>('/proxmox/config'),
+ saveConfig: (data: Omit<ProxmoxConfigData, 'token_configured'>) =>
+ api.post<ProxmoxConfigData>('/proxmox/config', data),
+}
+
export const designsApi = {
list: () => api.get<import('@/types').Design[]>('/designs'),
create: (data: { name: string; icon?: string; design_type?: string }) =>
diff --git a/frontend/src/components/modals/PendingDeviceModal.tsx b/frontend/src/components/modals/PendingDeviceModal.tsx
index d511dea..3d9170b 100644
--- a/frontend/src/components/modals/PendingDeviceModal.tsx
+++ b/frontend/src/components/modals/PendingDeviceModal.tsx
@@ -1,6 +1,7 @@
import { Globe, Router, Server, Layers, Box, Container, HardDrive, Cpu, Wifi, Circle, Network } from 'lucide-react'
import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog'
import { Button } from '@/components/ui/button'
+import type { NodeProperty } from '@/types'
interface Service {
port: number
@@ -26,6 +27,8 @@ export interface PendingDevice {
model?: string | null
vendor?: string | null
lqi?: number | null
+ // Display properties carried from discovery (e.g. Proxmox specs).
+ properties?: NodeProperty[]
discovered_at: string
// How many canvases (designs) this device already appears on. Computed server-side.
canvas_count?: number
diff --git a/frontend/src/components/modals/PendingDevicesModal.tsx b/frontend/src/components/modals/PendingDevicesModal.tsx
index 6d3af0d..8868074 100644
--- a/frontend/src/components/modals/PendingDevicesModal.tsx
+++ b/frontend/src/components/modals/PendingDevicesModal.tsx
@@ -73,13 +73,15 @@ const TYPE_ICONS: Record<string, React.ElementType> = {
generic: Circle,
}
-type SourceFilter = 'all' | 'ip' | 'zigbee' | 'zwave'
+type SourceFilter = 'all' | 'ip' | 'zigbee' | 'zwave' | 'proxmox'
type StatusFilter = 'pending' | 'hidden'
-function inferSource(d: PendingDevice): 'zigbee' | 'zwave' | 'ip' {
+function inferSource(d: PendingDevice): 'zigbee' | 'zwave' | 'proxmox' | 'ip' {
if (d.discovery_source === 'zwave') return 'zwave'
if (d.discovery_source === 'zigbee') return 'zigbee'
- if (d.ieee_address) return 'zigbee'
+ if (d.discovery_source === 'proxmox') return 'proxmox'
+ // Proxmox devices carry a synthetic 'pve-' ieee but are IP hosts, not mesh.
+ if (d.ieee_address && !d.ieee_address.startsWith('pve-')) return 'zigbee'
return 'ip'
}
@@ -279,7 +281,7 @@ export function PendingDevicesModal({ open, onClose, highlightId, initialStatus
? buildZwaveProperties(device)
: isZigbeeType(type)
? buildZigbeeProperties(device)
- : buildMacProperty(device.mac)
+ : [...(device.properties ?? []), ...buildMacProperty(device.mac)]
const nodeData = {
label: fallbackLabel,
type,
@@ -364,7 +366,7 @@ export function PendingDevicesModal({ open, onClose, highlightId, initialStatus
? buildZwaveProperties(d)
: isZigbeeType(type)
? buildZigbeeProperties(d)
- : buildMacProperty(d.mac),
+ : [...(d.properties ?? []), ...buildMacProperty(d.mac)],
},
})
})
@@ -503,6 +505,12 @@ export function PendingDevicesModal({ open, onClose, highlightId, initialStatus
>
Z-Wave
</button>
+ <button
+ onClick={() => setSourceFilter('proxmox')}
+ className={`px-2.5 py-1.5 transition-colors border-l border-border ${sourceFilter === 'proxmox' ? 'bg-[#e57000]/20 text-[#e57000]' : 'bg-[#0d1117] text-muted-foreground hover:text-foreground'}`}
+ >
+ Proxmox
+ </button>
</div>
<select
value={typeFilter}
@@ -666,10 +674,15 @@ function DeviceCard({ device, selected, selectMode, highlighted, onClick, cardRe
// (from the active theme / style section), instead of a flat grey.
const roleColor = resolveNodeColors({ type: roleType, custom_colors: undefined }, activeTheme).border
const label = deviceLabel(device)
- const sourceColor = source === 'zigbee' ? '#00d4ff' : source === 'zwave' ? '#ff6e00' : '#a855f7'
+ const sourceColor =
+ source === 'zigbee' ? '#00d4ff'
+ : source === 'zwave' ? '#ff6e00'
+ : source === 'proxmox' ? '#e57000'
+ : '#a855f7'
const sourceLabel =
source === 'zigbee' ? 'ZIGBEE'
: source === 'zwave' ? 'Z-WAVE'
+ : source === 'proxmox' ? 'PROXMOX'
: (device.discovery_source ?? 'IP').toUpperCase()
const services = device.services ?? []
const visibleServices = services.slice(0, 4)
diff --git a/frontend/src/components/modals/SettingsModal.tsx b/frontend/src/components/modals/SettingsModal.tsx
index 647997f..740fe9f 100644
--- a/frontend/src/components/modals/SettingsModal.tsx
+++ b/frontend/src/components/modals/SettingsModal.tsx
@@ -1,7 +1,7 @@
import { useState, useEffect } from 'react'
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter } from '@/components/ui/dialog'
import { Button } from '@/components/ui/button'
-import { settingsApi } from '@/api/client'
+import { settingsApi, proxmoxApi, type ProxmoxConfigData } from '@/api/client'
import { useCanvasStore } from '@/stores/canvasStore'
import { toast } from 'sonner'
import {
@@ -23,6 +23,9 @@ export function SettingsModal({ open, onClose }: SettingsModalProps) {
const [serviceCheckEnabled, setServiceCheckEnabled] = useState(false)
const [serviceInterval, setServiceInterval] = useState(300)
const [saving, setSaving] = useState(false)
+ const [pmConfig, setPmConfig] = useState<ProxmoxConfigData | null>(null)
+ const [pmSyncEnabled, setPmSyncEnabled] = useState(false)
+ const [pmInterval, setPmInterval] = useState(3600)
const [alignment, setAlignment] = useState<AlignmentSettings>(readAlignmentSettings)
const hideIp = useCanvasStore((s) => s.hideIp)
const setHideIp = useCanvasStore((s) => s.setHideIp)
@@ -36,6 +39,13 @@ export function SettingsModal({ open, onClose }: SettingsModalProps) {
setServiceInterval(res.data.service_check_interval)
})
.catch(() => {/* use default */})
+ proxmoxApi.getConfig()
+ .then((res) => {
+ setPmConfig(res.data)
+ setPmSyncEnabled(res.data.sync_enabled)
+ setPmInterval(res.data.sync_interval)
+ })
+ .catch(() => {/* proxmox not configured */})
}, [open])
useEffect(() => subscribeAlignmentSettings(setAlignment), [])
@@ -60,6 +70,15 @@ export function SettingsModal({ open, onClose }: SettingsModalProps) {
service_check_enabled: serviceCheckEnabled,
service_check_interval: serviceInterval,
})
+ if (pmConfig) {
+ await proxmoxApi.saveConfig({
+ host: pmConfig.host,
+ port: pmConfig.port,
+ verify_tls: pmConfig.verify_tls,
+ sync_enabled: pmSyncEnabled,
+ sync_interval: pmInterval,
+ })
+ }
toast.success('Settings saved')
onClose()
} catch {
@@ -128,6 +147,50 @@ export function SettingsModal({ open, onClose }: SettingsModalProps) {
</div>
)}
+ {/* Proxmox auto-sync */}
+ {!STANDALONE && pmConfig && (
+ <div className="pt-3 border-t border-border space-y-2">
+ <span className="text-xs font-medium text-muted-foreground uppercase tracking-wider">Proxmox auto-sync</span>
+ {!pmConfig.token_configured ? (
+ <p className="text-[10px] text-[#e3b341] leading-tight">
+ No API token configured. Set <span className="font-mono">PROXMOX_TOKEN_ID</span> and{' '}
+ <span className="font-mono">PROXMOX_TOKEN_SECRET</span> in the server .env to enable auto-sync.
+ </p>
+ ) : (
+ <>
+ <label className="flex items-center justify-between gap-2 cursor-pointer">
+ <span className="text-xs text-foreground">Auto-sync Proxmox inventory</span>
+ <input
+ type="checkbox"
+ checked={pmSyncEnabled}
+ onChange={(e) => setPmSyncEnabled(e.target.checked)}
+ className="cursor-pointer accent-[#e57000]"
+ aria-label="Toggle Proxmox auto-sync"
+ />
+ </label>
+ <div className={pmSyncEnabled ? 'space-y-1.5' : 'space-y-1.5 opacity-50 pointer-events-none'}>
+ <label className="text-xs text-muted-foreground">Sync interval (s)</label>
+ <div className="flex items-center gap-2">
+ <input
+ type="number"
+ min={300}
+ max={86400}
+ value={pmInterval}
+ onChange={(e) => { const v = Number(e.target.value); if (!isNaN(v)) setPmInterval(v) }}
+ className="w-24 px-2 py-1 rounded-md text-xs font-mono bg-[#0d1117] border border-border text-foreground focus:outline-none focus:border-[#e57000]"
+ aria-label="Proxmox sync interval"
+ />
+ <span className="text-xs text-muted-foreground">seconds</span>
+ </div>
+ <p className="text-[10px] text-muted-foreground leading-tight">
+ Re-imports hosts/VMs/LXC into the pending inventory. Min 300s (5 min).
+ </p>
+ </div>
+ </>
+ )}
+ </div>
+ )}
+
{/* Canvas */}
<div className="pt-3 border-t border-border space-y-3">
<span className="text-xs font-medium text-muted-foreground uppercase tracking-wider">Canvas</span>
diff --git a/frontend/src/components/modals/__tests__/PendingDevicesModal.test.tsx b/frontend/src/components/modals/__tests__/PendingDevicesModal.test.tsx
index ae322fc..4e7d230 100644
--- a/frontend/src/components/modals/__tests__/PendingDevicesModal.test.tsx
+++ b/frontend/src/components/modals/__tests__/PendingDevicesModal.test.tsx
@@ -84,6 +84,24 @@ const DEVICE_ZWAVE = {
discovered_at: '2026-01-03T00:00:00Z',
}
+const DEVICE_PROXMOX = {
+ id: 'dev-d',
+ ip: '10.0.0.5',
+ hostname: 'web',
+ mac: null,
+ os: null,
+ services: [],
+ suggested_type: 'vm',
+ status: 'pending',
+ discovery_source: 'proxmox',
+ ieee_address: 'pve-pve1-101',
+ friendly_name: 'web',
+ vendor: 'Proxmox VE',
+ model: 'QEMU',
+ properties: [{ key: 'CPU Cores', value: '2', icon: 'Cpu', visible: false }],
+ discovered_at: '2026-01-04T00:00:00Z',
+}
+
beforeEach(() => {
vi.clearAllMocks()
vi.mocked(useCanvasStore).mockReturnValue({
@@ -174,6 +192,23 @@ describe('PendingDevicesModal', () => {
expect(screen.getByTestId('pending-card-dev-c')).toBeInTheDocument()
})
+ it('shows source chip PROXMOX for a proxmox device (not zigbee despite ieee)', async () => {
+ mockPending.mockResolvedValue({ data: [DEVICE_PROXMOX] })
+ render(<PendingDevicesModal {...baseProps} />)
+ await waitFor(() => expect(screen.getByTestId('pending-card-dev-d')).toBeInTheDocument())
+ expect(screen.getByText('PROXMOX')).toBeInTheDocument()
+ expect(screen.queryByText('ZIGBEE')).not.toBeInTheDocument()
+ })
+
+ it('filters by source (proxmox only)', async () => {
+ mockPending.mockResolvedValue({ data: [DEVICE_IP, DEVICE_PROXMOX] })
+ render(<PendingDevicesModal {...baseProps} />)
+ await waitFor(() => expect(screen.getByTestId('pending-card-dev-a')).toBeInTheDocument())
+ fireEvent.click(screen.getByRole('button', { name: 'Proxmox' }))
+ expect(screen.queryByTestId('pending-card-dev-a')).not.toBeInTheDocument()
+ expect(screen.getByTestId('pending-card-dev-d')).toBeInTheDocument()
+ })
+
it('filters by suggested type', async () => {
render(<PendingDevicesModal {...baseProps} />)
await waitFor(() => expect(screen.getByTestId('pending-card-dev-a')).toBeInTheDocument())
diff --git a/frontend/src/components/modals/__tests__/SettingsModal.test.tsx b/frontend/src/components/modals/__tests__/SettingsModal.test.tsx
index 773e4b0..6426d39 100644
--- a/frontend/src/components/modals/__tests__/SettingsModal.test.tsx
+++ b/frontend/src/components/modals/__tests__/SettingsModal.test.tsx
@@ -8,9 +8,13 @@ vi.mock('@/api/client', () => ({
get: vi.fn(),
save: vi.fn(),
},
+ proxmoxApi: {
+ getConfig: vi.fn(),
+ saveConfig: vi.fn(),
+ },
}))
-import { settingsApi } from '@/api/client'
+import { settingsApi, proxmoxApi } from '@/api/client'
import { toast } from 'sonner'
import { useCanvasStore } from '@/stores/canvasStore'
@@ -19,6 +23,8 @@ describe('SettingsModal', () => {
vi.clearAllMocks()
vi.mocked(settingsApi.get).mockResolvedValue({ data: { interval_seconds: 60, service_check_enabled: false, service_check_interval: 300 } } as never)
vi.mocked(settingsApi.save).mockResolvedValue({ data: { interval_seconds: 60, service_check_enabled: false, service_check_interval: 300 } } as never)
+ vi.mocked(proxmoxApi.getConfig).mockRejectedValue(new Error('not configured'))
+ vi.mocked(proxmoxApi.saveConfig).mockResolvedValue({ data: {} } as never)
vi.mocked(toast.success).mockReset()
vi.mocked(toast.error).mockReset()
})
diff --git a/frontend/src/components/panels/Sidebar.tsx b/frontend/src/components/panels/Sidebar.tsx
index 758ec67..2d48cda 100644
--- a/frontend/src/components/panels/Sidebar.tsx
+++ b/frontend/src/components/panels/Sidebar.tsx
@@ -1,5 +1,5 @@
import { useState, useCallback, useEffect } from 'react'
-import { Plus, Save, ScanLine, ChevronLeft, ChevronRight, LayoutDashboard, Clock, EyeOff, Square, Settings, LogOut, Network, RadioTower, Type, PlusCircle, Pencil, Trash2 } from 'lucide-react'
+import { Plus, Save, ScanLine, ChevronLeft, ChevronRight, LayoutDashboard, Clock, EyeOff, Square, Settings, LogOut, Network, RadioTower, Server, Type, PlusCircle, Pencil, Trash2 } from 'lucide-react'
import { Logo } from '@/components/ui/Logo'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
import { useCanvasStore } from '@/stores/canvasStore'
@@ -27,13 +27,14 @@ interface SidebarProps {
onScan: () => void
onZigbeeImport: () => void
onZwaveImport: () => void
+ onProxmoxImport: () => void
onSave: () => void
onOpenSettings: () => void
onOpenHistory: () => void
onOpenPending: (deviceId?: string, status?: 'pending' | 'hidden') => void
}
-export function Sidebar({ onAddNode, onAddGroupRect, onAddText, onScan, onZigbeeImport, onZwaveImport, onSave, onOpenSettings, onOpenHistory, onOpenPending }: SidebarProps) {
+export function Sidebar({ onAddNode, onAddGroupRect, onAddText, onScan, onZigbeeImport, onZwaveImport, onProxmoxImport, onSave, onOpenSettings, onOpenHistory, onOpenPending }: SidebarProps) {
const [collapsed, setCollapsed] = useState(false)
const logout = useAuthStore((s) => s.logout)
const { designs, activeDesignId, setActiveDesign, addDesign, updateDesign, removeDesign } = useDesignStore()
@@ -265,6 +266,7 @@ export function Sidebar({ onAddNode, onAddGroupRect, onAddText, onScan, onZigbee
{!STANDALONE && <SidebarItem icon={ScanLine} label="Scan Network" collapsed={collapsed} onClick={handleScan} />}
{!STANDALONE && <SidebarItem icon={Network} label="Zigbee Import" collapsed={collapsed} onClick={onZigbeeImport} />}
{!STANDALONE && <SidebarItem icon={RadioTower} label="Z-Wave Import" collapsed={collapsed} onClick={onZwaveImport} />}
+ {!STANDALONE && <SidebarItem icon={Server} label="Proxmox Import" collapsed={collapsed} onClick={onProxmoxImport} />}
<SidebarItem
icon={Save}
label="Save Canvas"
diff --git a/frontend/src/components/proxmox/ProxmoxImportModal.tsx b/frontend/src/components/proxmox/ProxmoxImportModal.tsx
new file mode 100644
index 0000000..02812e2
--- /dev/null
+++ b/frontend/src/components/proxmox/ProxmoxImportModal.tsx
@@ -0,0 +1,385 @@
+import { useState } from 'react'
+import { Server, Box, Container, CheckCircle2, XCircle, Loader2, Plus } from 'lucide-react'
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter } from '@/components/ui/dialog'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+import { proxmoxApi, type ProxmoxConnection } from '@/api/client'
+import { toast } from 'sonner'
+import type { ProxmoxNode, ProxmoxEdge, ProxmoxNodeType } from './types'
+
+interface ProxmoxImportModalProps {
+ open: boolean
+ onClose: () => void
+ onAddToCanvas: (nodes: ProxmoxNode[], edges: ProxmoxEdge[]) => void
+ onPendingImported?: () => void
+}
+
+type ImportMode = 'pending' | 'canvas'
+
+const ACCENT = '#e57000'
+
+interface ConnectionForm {
+ host: string
+ port: string
+ token_id: string
+ token_secret: string
+ verify_tls: boolean
+}
+
+const DEFAULT_FORM: ConnectionForm = {
+ host: '',
+ port: '8006',
+ token_id: '',
+ token_secret: '',
+ verify_tls: true,
+}
+
+const DEVICE_TYPE_ICON: Record<ProxmoxNodeType, typeof Server> = {
+ proxmox: Server,
+ vm: Box,
+ lxc: Container,
+}
+
+const DEVICE_TYPE_LABEL: Record<ProxmoxNodeType, string> = {
+ proxmox: 'Hosts',
+ vm: 'Virtual Machines',
+ lxc: 'LXC Containers',
+}
+
+const DEVICE_TYPE_COLOR: Record<ProxmoxNodeType, string> = {
+ proxmox: '#e57000',
+ vm: '#00d4ff',
+ lxc: '#39d353',
+}
+
+export function ProxmoxImportModal({ open, onClose, onAddToCanvas, onPendingImported }: ProxmoxImportModalProps) {
+ const [form, setForm] = useState<ConnectionForm>(DEFAULT_FORM)
+ const [connectionStatus, setConnectionStatus] = useState<'idle' | 'testing' | 'ok' | 'fail'>('idle')
+ const [connectionMsg, setConnectionMsg] = useState('')
+ const [loading, setLoading] = useState(false)
+ const [devices, setDevices] = useState<ProxmoxNode[]>([])
+ const [edges, setEdges] = useState<ProxmoxEdge[]>([])
+ const [checked, setChecked] = useState<Set<string>>(new Set())
+ const [importMode, setImportMode] = useState<ImportMode>('pending')
+
+ const updateField = (field: keyof ConnectionForm, value: string) =>
+ setForm((f) => ({ ...f, [field]: value }))
+
+ const buildPayload = (): ProxmoxConnection => ({
+ host: form.host.trim(),
+ port: Number(form.port) || 8006,
+ token_id: form.token_id.trim() || undefined,
+ token_secret: form.token_secret || undefined,
+ verify_tls: form.verify_tls,
+ })
+
+ const extractError = (err: unknown): string | undefined => {
+ if (err && typeof err === 'object' && 'response' in err) {
+ return (err as { response?: { data?: { detail?: string } } }).response?.data?.detail
+ }
+ return undefined
+ }
+
+ const handleTestConnection = async () => {
+ if (!form.host.trim()) { toast.error('Enter a Proxmox host'); return }
+ setConnectionStatus('testing')
+ try {
+ const res = await proxmoxApi.testConnection(buildPayload())
+ setConnectionStatus(res.data.connected ? 'ok' : 'fail')
+ setConnectionMsg(res.data.message)
+ } catch (err) {
+ setConnectionStatus('fail')
+ setConnectionMsg(extractError(err) ?? 'Request failed — check host address')
+ }
+ }
+
+ const handleFetchDevices = async () => {
+ if (!form.host.trim()) { toast.error('Enter a Proxmox host'); return }
+ setLoading(true)
+ try {
+ if (importMode === 'pending') {
+ await proxmoxApi.importToPending(buildPayload())
+ toast.success('Proxmox import started — track progress in Scan History')
+ onPendingImported?.()
+ handleClose()
+ } else {
+ const res = await proxmoxApi.importNetwork(buildPayload())
+ setDevices(res.data.nodes)
+ setEdges(res.data.edges)
+ setChecked(new Set(res.data.nodes.map((n) => n.id)))
+ if (res.data.device_count === 0) {
+ toast.info('No Proxmox guests found')
+ } else {
+ toast.success(`Found ${res.data.device_count} device${res.data.device_count !== 1 ? 's' : ''}`)
+ }
+ }
+ } catch (err: unknown) {
+ toast.error(extractError(err) ?? 'Failed to fetch Proxmox inventory')
+ } finally {
+ setLoading(false)
+ }
+ }
+
+ const toggleCheck = (id: string) =>
+ setChecked((prev) => {
+ const next = new Set(prev)
+ if (next.has(id)) next.delete(id); else next.add(id)
+ return next
+ })
+
+ const toggleAll = () => {
+ setChecked(checked.size === devices.length ? new Set() : new Set(devices.map((d) => d.id)))
+ }
+
+ const handleAddToCanvas = () => {
+ const selectedDevices = devices.filter((d) => checked.has(d.id))
+ const selectedIds = new Set(selectedDevices.map((d) => d.id))
+ const selectedEdges = edges.filter((e) => selectedIds.has(e.source) && selectedIds.has(e.target))
+ onAddToCanvas(selectedDevices, selectedEdges)
+ toast.success(`Added ${selectedDevices.length} device${selectedDevices.length !== 1 ? 's' : ''} to canvas`)
+ onClose()
+ }
+
+ const handleClose = () => {
+ setDevices([])
+ setEdges([])
+ setChecked(new Set())
+ setConnectionStatus('idle')
+ setConnectionMsg('')
+ setImportMode('pending')
+ onClose()
+ }
+
+ const groupedDevices: Record<ProxmoxNodeType, ProxmoxNode[]> = {
+ proxmox: devices.filter((d) => d.type === 'proxmox'),
+ vm: devices.filter((d) => d.type === 'vm'),
+ lxc: devices.filter((d) => d.type === 'lxc'),
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={(v) => !v && handleClose()}>
+ <DialogContent className="bg-[#161b22] border-border max-w-xl max-h-[85vh] flex flex-col">
+ <DialogHeader>
+ <DialogTitle className="text-foreground flex items-center gap-2">
+ <Server size={16} style={{ color: ACCENT }} />
+ Proxmox VE Import
+ </DialogTitle>
+ </DialogHeader>
+
+ <div className="flex-1 overflow-y-auto space-y-4 py-2 min-h-0">
+ <div className="space-y-3">
+ <div className="grid grid-cols-2 gap-3">
+ <div className="col-span-2 space-y-1">
+ <Label className="text-xs text-muted-foreground">Proxmox Host</Label>
+ <Input
+ value={form.host}
+ onChange={(e) => updateField('host', e.target.value)}
+ placeholder="192.168.1.x or pve.local"
+ className="font-mono text-sm bg-[#0d1117] border-border"
+ />
+ </div>
+ <div className="space-y-1">
+ <Label className="text-xs text-muted-foreground">Port</Label>
+ <Input
+ value={form.port}
+ onChange={(e) => updateField('port', e.target.value)}
+ placeholder="8006"
+ type="number"
+ className="font-mono text-sm bg-[#0d1117] border-border"
+ />
+ </div>
+ <div className="space-y-1">
+ <Label className="text-xs text-muted-foreground">Token ID</Label>
+ <Input
+ value={form.token_id}
+ onChange={(e) => updateField('token_id', e.target.value)}
+ placeholder="user@pam!tokenname"
+ className="font-mono text-sm bg-[#0d1117] border-border"
+ />
+ </div>
+ <div className="col-span-2 space-y-1">
+ <Label className="text-xs text-muted-foreground">Token Secret</Label>
+ <Input
+ value={form.token_secret}
+ onChange={(e) => updateField('token_secret', e.target.value)}
+ placeholder="••••••••-••••-••••-••••-••••••••••••"
+ type="password"
+ autoComplete="new-password"
+ className="text-sm bg-[#0d1117] border-border"
+ />
+ </div>
+ <div className="col-span-2 flex items-center gap-4 pt-1">
+ <label className="flex items-center gap-1.5 text-xs text-muted-foreground cursor-pointer">
+ <input
+ type="checkbox"
+ checked={form.verify_tls}
+ onChange={(e) => setForm((f) => ({ ...f, verify_tls: e.target.checked }))}
+ className="w-3 h-3 cursor-pointer"
+ style={{ accentColor: ACCENT }}
+ />
+ Verify TLS certificate
+ </label>
+ </div>
+ </div>
+
+ {connectionStatus !== 'idle' && (
+ <div className={`flex items-center gap-1.5 text-xs px-2 py-1.5 rounded-md border ${
+ connectionStatus === 'ok'
+ ? 'bg-[#39d353]/10 border-[#39d353]/30 text-[#39d353]'
+ : connectionStatus === 'fail'
+ ? 'bg-[#f85149]/10 border-[#f85149]/30 text-[#f85149]'
+ : 'bg-[#e3b341]/10 border-[#e3b341]/30 text-[#e3b341]'
+ }`}>
+ {connectionStatus === 'testing' && <Loader2 size={12} className="animate-spin" />}
+ {connectionStatus === 'ok' && <CheckCircle2 size={12} />}
+ {connectionStatus === 'fail' && <XCircle size={12} />}
+ <span>{connectionStatus === 'testing' ? 'Testing…' : connectionMsg}</span>
+ </div>
+ )}
+
+ <div className="flex items-center gap-3 text-xs">
+ <span className="text-muted-foreground">Send devices to:</span>
+ <label className="flex items-center gap-1.5 cursor-pointer text-foreground">
+ <input
+ type="radio"
+ name="proxmox-import-mode"
+ checked={importMode === 'pending'}
+ onChange={() => setImportMode('pending')}
+ className="cursor-pointer"
+ style={{ accentColor: ACCENT }}
+ />
+ Pending section
+ </label>
+ <label className="flex items-center gap-1.5 cursor-pointer text-foreground">
+ <input
+ type="radio"
+ name="proxmox-import-mode"
+ checked={importMode === 'canvas'}
+ onChange={() => setImportMode('canvas')}
+ className="cursor-pointer"
+ style={{ accentColor: ACCENT }}
+ />
+ Canvas directly
+ </label>
+ </div>
+ <div className="flex gap-2">
+ <Button
+ size="sm"
+ variant="ghost"
+ className="gap-1.5 text-muted-foreground hover:text-foreground border border-border hover:bg-[#21262d]"
+ onClick={handleTestConnection}
+ disabled={connectionStatus === 'testing' || loading}
+ >
+ {connectionStatus === 'testing'
+ ? <Loader2 size={13} className="animate-spin" />
+ : <CheckCircle2 size={13} />}
+ Test Connection
+ </Button>
+ <Button
+ size="sm"
+ style={{ background: ACCENT, color: '#0d1117' }}
+ className="gap-1.5"
+ onClick={handleFetchDevices}
+ disabled={loading || connectionStatus === 'testing'}
+ >
+ {loading ? <Loader2 size={13} className="animate-spin" /> : <Server size={13} />}
+ {importMode === 'pending' ? 'Import to Pending' : 'Fetch Inventory'}
+ </Button>
+ </div>
+ <p className="text-[11px] text-muted-foreground italic">
+ Leave the token blank to use the token configured on the server (.env).
+ A read-only <span className="font-mono">PVEAuditor</span> role is enough.
+ </p>
+ </div>
+
+ {devices.length > 0 && (
+ <div className="space-y-2">
+ <div className="flex items-center justify-between">
+ <div className="flex items-center gap-1.5">
+ <input
+ type="checkbox"
+ checked={checked.size === devices.length}
+ ref={(el) => { if (el) el.indeterminate = checked.size > 0 && checked.size < devices.length }}
+ onChange={toggleAll}
+ className="w-3 h-3 cursor-pointer"
+ style={{ accentColor: ACCENT }}
+ title="Select all"
+ />
+ <span className="text-xs font-medium text-muted-foreground uppercase tracking-wider">
+ Devices ({checked.size}/{devices.length} selected)
+ </span>
+ </div>
+ </div>
+
+ {(Object.entries(groupedDevices) as [ProxmoxNodeType, ProxmoxNode[]][])
+ .filter(([, group]) => group.length > 0)
+ .map(([type, group]) => {
+ const Icon = DEVICE_TYPE_ICON[type]
+ const color = DEVICE_TYPE_COLOR[type]
+ return (
+ <div key={type}>
+ <div className="flex items-center gap-1.5 mb-1">
+ <Icon size={11} style={{ color }} />
+ <span className="text-[10px] font-medium uppercase tracking-wider" style={{ color }}>
+ {DEVICE_TYPE_LABEL[type]} ({group.length})
+ </span>
+ </div>
+ {group.map((device) => (
+ <div
+ key={device.id}
+ className={`flex items-start gap-2 p-2 mb-1 rounded-md text-xs cursor-pointer transition-colors border ${
+ checked.has(device.id)
+ ? 'bg-[#21262d] border-[#e57000]/40'
+ : 'bg-[#21262d] border-transparent hover:bg-[#30363d]'
+ }`}
+ onClick={() => toggleCheck(device.id)}
+ >
+ <input
+ type="checkbox"
+ checked={checked.has(device.id)}
+ onChange={() => toggleCheck(device.id)}
+ onClick={(e) => e.stopPropagation()}
+ className="w-3 h-3 mt-0.5 cursor-pointer shrink-0"
+ style={{ accentColor: ACCENT }}
+ />
+ <div className="flex-1 min-w-0">
+ <div className="text-foreground font-medium truncate">{device.label}</div>
+ {device.ip && (
+ <div className="font-mono text-[10px] text-muted-foreground truncate">{device.ip}</div>
+ )}
+ <div className="text-[10px] text-muted-foreground truncate">
+ {[
+ device.cpu_count ? `${device.cpu_count} vCPU` : null,
+ device.ram_gb ? `${device.ram_gb} GB RAM` : null,
+ device.status,
+ ].filter(Boolean).join(' · ')}
+ </div>
+ </div>
+ </div>
+ ))}
+ </div>
+ )
+ })}
+ </div>
+ )}
+ </div>
+
+ <DialogFooter className="gap-2 shrink-0 pt-2 border-t border-border">
+ <Button variant="ghost" onClick={handleClose}>Cancel</Button>
+ {devices.length > 0 && (
+ <Button
+ onClick={handleAddToCanvas}
+ disabled={checked.size === 0}
+ style={{ background: ACCENT, color: '#0d1117' }}
+ className="gap-1.5"
+ >
+ <Plus size={13} />
+ Add {checked.size} to Canvas
+ </Button>
+ )}
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/frontend/src/components/proxmox/__tests__/ProxmoxImportModal.test.tsx b/frontend/src/components/proxmox/__tests__/ProxmoxImportModal.test.tsx
new file mode 100644
index 0000000..dd35d39
--- /dev/null
+++ b/frontend/src/components/proxmox/__tests__/ProxmoxImportModal.test.tsx
@@ -0,0 +1,121 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { ProxmoxImportModal } from '../ProxmoxImportModal'
+
+vi.mock('@/api/client', () => ({
+ proxmoxApi: {
+ testConnection: vi.fn(),
+ importNetwork: vi.fn(),
+ importToPending: vi.fn(),
+ },
+}))
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn(), info: vi.fn() } }))
+
+import { proxmoxApi } from '@/api/client'
+import { toast } from 'sonner'
+
+const defaultProps = {
+ open: true,
+ onClose: vi.fn(),
+ onAddToCanvas: vi.fn(),
+ onPendingImported: vi.fn(),
+}
+
+const sampleNodes = [
+ {
+ id: 'pve-node-pve1', label: 'pve1', type: 'proxmox' as const,
+ ieee_address: 'pve-node-pve1', hostname: 'pve1', ip: null, status: 'online',
+ cpu_count: 8, ram_gb: 16, disk_gb: 500, vendor: 'Proxmox VE', model: null, parent_ieee: null,
+ },
+ {
+ id: 'pve-pve1-101', label: 'web', type: 'vm' as const,
+ ieee_address: 'pve-pve1-101', hostname: 'web', ip: '10.0.0.5', status: 'online',
+ cpu_count: 2, ram_gb: 4, disk_gb: 32, vendor: 'Proxmox VE', model: 'QEMU', parent_ieee: 'pve-node-pve1',
+ },
+]
+
+describe('ProxmoxImportModal', () => {
+ beforeEach(() => {
+ vi.mocked(proxmoxApi.testConnection).mockReset()
+ vi.mocked(proxmoxApi.importNetwork).mockReset()
+ vi.mocked(proxmoxApi.importToPending).mockReset()
+ vi.mocked(toast.success).mockReset()
+ vi.mocked(toast.error).mockReset()
+ vi.mocked(toast.info).mockReset()
+ defaultProps.onClose.mockReset()
+ defaultProps.onAddToCanvas.mockReset()
+ defaultProps.onPendingImported.mockReset()
+ })
+
+ it('renders nothing when closed', () => {
+ const { container } = render(<ProxmoxImportModal {...defaultProps} open={false} />)
+ expect(container.querySelector('[role="dialog"]')).toBeNull()
+ })
+
+ it('renders token fields with a masked secret input', () => {
+ render(<ProxmoxImportModal {...defaultProps} />)
+ expect(screen.getByText('Proxmox VE Import')).toBeDefined()
+ expect(screen.getByPlaceholderText('user@pam!tokenname')).toBeDefined()
+ const secret = document.querySelector('input[type="password"]')
+ expect(secret).not.toBeNull()
+ })
+
+ it('errors when testing without a host', async () => {
+ render(<ProxmoxImportModal {...defaultProps} />)
+ fireEvent.click(screen.getByRole('button', { name: /test connection/i }))
+ await waitFor(() => expect(toast.error).toHaveBeenCalledWith('Enter a Proxmox host'))
+ expect(proxmoxApi.testConnection).not.toHaveBeenCalled()
+ })
+
+ it('shows connection message on successful test', async () => {
+ vi.mocked(proxmoxApi.testConnection).mockResolvedValue({
+ data: { connected: true, message: 'Connected to Proxmox VE 8.2.2' },
+ } as never)
+ render(<ProxmoxImportModal {...defaultProps} />)
+ fireEvent.change(screen.getByPlaceholderText('192.168.1.x or pve.local'), { target: { value: 'pve' } })
+ fireEvent.click(screen.getByRole('button', { name: /test connection/i }))
+ await waitFor(() => expect(screen.getByText('Connected to Proxmox VE 8.2.2')).toBeDefined())
+ })
+
+ it('imports to pending by default and notifies parent', async () => {
+ vi.mocked(proxmoxApi.importToPending).mockResolvedValue({
+ data: { id: 'run-1', status: 'running', kind: 'proxmox', ranges: [], devices_found: 0, started_at: '', finished_at: null, error: null },
+ } as never)
+ render(<ProxmoxImportModal {...defaultProps} />)
+ fireEvent.change(screen.getByPlaceholderText('192.168.1.x or pve.local'), { target: { value: 'pve' } })
+ fireEvent.click(screen.getByRole('button', { name: /import to pending/i }))
+ await waitFor(() => expect(proxmoxApi.importToPending).toHaveBeenCalled())
+ expect(defaultProps.onPendingImported).toHaveBeenCalled()
+ expect(proxmoxApi.importNetwork).not.toHaveBeenCalled()
+ })
+
+ it('fetches inventory in canvas mode and groups by type', async () => {
+ vi.mocked(proxmoxApi.importNetwork).mockResolvedValue({
+ data: { nodes: sampleNodes, edges: [{ source: 'pve-node-pve1', target: 'pve-pve1-101' }], device_count: 2 },
+ } as never)
+ render(<ProxmoxImportModal {...defaultProps} />)
+ fireEvent.click(screen.getByRole('radio', { name: /canvas directly/i }))
+ fireEvent.change(screen.getByPlaceholderText('192.168.1.x or pve.local'), { target: { value: 'pve' } })
+ fireEvent.click(screen.getByRole('button', { name: /fetch inventory/i }))
+ await waitFor(() => {
+ expect(screen.getByText('pve1')).toBeDefined()
+ expect(screen.getByText('web')).toBeDefined()
+ })
+ expect(toast.success).toHaveBeenCalledWith('Found 2 devices')
+ })
+
+ it('sends the token from the form in the payload', async () => {
+ vi.mocked(proxmoxApi.importNetwork).mockResolvedValue({
+ data: { nodes: [], edges: [], device_count: 0 },
+ } as never)
+ render(<ProxmoxImportModal {...defaultProps} />)
+ fireEvent.click(screen.getByRole('radio', { name: /canvas directly/i }))
+ fireEvent.change(screen.getByPlaceholderText('192.168.1.x or pve.local'), { target: { value: 'pve' } })
+ fireEvent.change(screen.getByPlaceholderText('user@pam!tokenname'), { target: { value: 'root@pam!hl' } })
+ fireEvent.click(screen.getByRole('button', { name: /fetch inventory/i }))
+ await waitFor(() => expect(proxmoxApi.importNetwork).toHaveBeenCalled())
+ const payload = vi.mocked(proxmoxApi.importNetwork).mock.calls[0][0]
+ expect(payload.token_id).toBe('root@pam!hl')
+ expect(payload.port).toBe(8006)
+ })
+})
diff --git a/frontend/src/components/proxmox/types.ts b/frontend/src/components/proxmox/types.ts
new file mode 100644
index 0000000..b0a4b8c
--- /dev/null
+++ b/frontend/src/components/proxmox/types.ts
@@ -0,0 +1,30 @@
+/** Shared Proxmox VE import type definitions for the frontend. */
+
+export type ProxmoxNodeType = 'proxmox' | 'vm' | 'lxc'
+
+export interface ProxmoxNode {
+ id: string
+ label: string
+ type: ProxmoxNodeType
+ ieee_address: string
+ hostname?: string | null
+ ip?: string | null
+ status: string
+ cpu_count?: number | null
+ ram_gb?: number | null
+ disk_gb?: number | null
+ vendor?: string | null
+ model?: string | null
+ parent_ieee?: string | null
+}
+
+export interface ProxmoxEdge {
+ source: string
+ target: string
+}
+
+export interface ProxmoxImportResponse {
+ nodes: ProxmoxNode[]
+ edges: ProxmoxEdge[]
+ device_count: number
+}