theProx

Proxmox Remote Management Platform — zentrales WebUI zur Verwaltung mehrerer Proxmox-Hosts über ausgehende WebSocket-Agenten.

---

Architektur

┌──────────────────────────────────────────────────────────┐
│  Client (Browser)                                        │
│  :8080 (intern, VPN) ← nginx-intern                     │
└───────────────┬──────────────────────────────────────────┘
                │
┌───────────────▼──────────────────────────────────────────┐
│  FastAPI Backend  :8765                                  │
│  ┌─────────────┐  ┌────────────────┐  ┌───────────────┐ │
│  │ REST API    │  │ WebSocket      │  │ Scheduler     │ │
│  │ /api/*      │  │ /ws/agent      │  │ (async, 60s)  │ │
│  │ /auth/*     │  │ /ws/terminal/  │  └───────────────┘ │
│  └─────────────┘  └────────────────┘                    │
└───────────────┬──────────────────────────────────────────┘
                │ WebSocket (ausgehend, Agent verbindet sich)
┌───────────────▼──────────────────────────────────────────┐
│  Proxmox-Host (Node-Agent)                               │
│  theprox-node-agent (Rust) — root, verbindet zu Server   │
│  pvesh / qm / pct CLI → Proxmox API                     │
│  TCP :9100 ◄── VM-Guest-Agenten (Metrics + Scans)       │
└───────────────┬──────────────────────────────────────────┘
                │ TCP (JSON-Lines, Guest verbindet zu Host)
┌───────────────▼──────────────────────────────────────────┐
│  VM Guest-Agent (Rust)                                   │
│  theprox-vm-agent — läuft in Linux/FreeBSD/Windows-VMs   │
│  sendet Metrics (15s) + Scans (5min) an Host-Agent       │
└──────────────────────────────────────────────────────────┘

Kein offener Port auf den Proxmox-Hosts erforderlich. Der Node-Agent verbindet sich ausgehend zum Server. VM-Guest-Agenten verbinden sich ausgehend zum Host-Agent (Port 9100).

---

UI-Aufbau

Die App ist ein Single-Page-Dashboard unter / (kein Modul-Routing mehr). Node-Übersicht mit Inline-Graphen + KPIs; Detailfunktionen liegen in ausklappbaren Panels (pro Node) und einem VM-Modal (pro VM/CT).

Bereich	Inhalt
Dashboard (/)	Node-Liste, Host-Identity, Inline-Graphen, KPIs, Cluster-Alerts, Cross-Tenant Bulk-Update
Node-Panels (admin-node-tabs/)	Updates · Backup · Ports · Network · Jobs · Security · Audit · Logs · Command · Scheduler
VM-Modal (admin-vm-modal/tabs/)	Info · Monitoring · Updates · Backups · Snapshots · Storage · Network · Ports · Docker · Commands · Security · Jobs · Audit · Logs
Notizen (/notizen)	mustchange/Changelog-Notizen pro VM und global
Profil (/profil)	Eigenes Konto, Passwort, Sessions
Einstellungen (/settings)	OIDC/SSO, SMTP, Benachrichtigungen, SSL/ACME, Mandanten, User-CRUD, Host-Provisioning

VM-Updates laufen über den VM-Guest-Agent bzw. QEMU-Agent, Backups via vzdump, Terminal via PTY direkt auf Host/VM.

---

Stack

Komponente	Technologie
Backend	Python 3.11 · FastAPI · SQLAlchemy async · PostgreSQL · Alembic
Frontend	SvelteKit 5 (Runes) · TypeScript · Inter + IBM Plex Mono
Node-Agent	Python 3 · websockets · pvesh/qm/pct CLI (gebundleter Monolith)
VM Guest-Agent	Rust (static musl) · Linux/FreeBSD/Windows · TCP-JSON-Lines
Infrastruktur	Docker Compose · nginx (dual: public + intern)
Auth	JWT (httpOnly Cookie) · RBAC (superadmin + per-Tenant read/write)

---

Schnellstart

Voraussetzungen

• Docker + Docker Compose
• Zugang zu einem Proxmox-Host (für Agent-Installation)

1. Konfiguration

.env in server/ erstellen:

DB_PASSWORD=<sicheres-passwort>
JWT_SECRET=<zufälliger-string-min-32-zeichen>
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=<sicheres-passwort>
SERVER_URL=http://DEINE-SERVER-IP:8765

2. Stack starten

cd server
docker compose up -d

Dienste:

• :8080 — WebUI (intern/VPN)
• :8765 — Agent-WebSocket (öffentlich erreichbar)

3. Ersten Proxmox-Host registrieren

1. Browser → http://SERVER:8080 → Login
2. Einstellungen → Host-Provisioning → Host registrieren (nur Superadmin)
3. Generierten curl-Befehl auf dem Proxmox-Host als root ausführen:

curl -fsSL http://SERVER:8765/install/<TOKEN> | bash

Der Agent verbindet sich automatisch und erscheint nach wenigen Sekunden als Online.

---

Projektstruktur

theProx/
├── server/                    FastAPI Backend
│   ├── main.py                App-Einstiegspunkt, WebSocket- + Install-Endpoints
│   ├── database.py            AsyncSession, get_db, init_db (Alembic)
│   ├── scheduler.py           Background-Scheduler (asyncio)
│   ├── rate_limit.py          Rate-Limiting
│   ├── auth/
│   │   ├── jwt.py             Token-Encode/Decode
│   │   ├── rbac.py            RBAC: require_superadmin/read/write, check_*_scope
│   │   └── local.py           Lokaler Admin-Fallback
│   ├── models/                SQLAlchemy ORM-Modelle
│   ├── routers/               FastAPI Router (admin/deploy/backup/docker/…)
│   ├── websocket/
│   │   ├── manager.py         AgentManager, Future-Pattern für Commands
│   │   └── agent_ws.py        WebSocket-Endpoint für Agenten
│   ├── tunneling/             Reverse-Tunnel-Manager (Guacamole/guaclite)
│   ├── guaclite/              schlanker Guacamole-Client
│   ├── services/              Service-Layer
│   ├── settings/              Systemkonfiguration (JSONB in DB)
│   ├── migrations/            Alembic-Migrationen (ab 0001_baseline)
│   ├── nginx/
│   │   ├── public.conf        :8765 — nur /ws/agent
│   │   └── intern.conf        :8080 — WebUI + API
│   ├── docker-compose.yml
│   └── Dockerfile
├── frontend/                  SvelteKit Frontend
│   └── src/
│       ├── lib/
│       │   ├── api.ts         Alle API-Methoden
│       │   ├── stores/        Svelte Stores (auth, nodes)
│       │   └── components/    admin-node-tabs/, admin-vm-modal/, ui/, Terminal …
│       └── routes/
│           ├── login/
│           ├── terminal/
│           └── (app)/         Geschützte Seiten
│               ├── +layout.svelte   Sidebar-Shell
│               ├── +page.svelte     Dashboard (Nodes + VM-Modal)
│               ├── notizen/
│               ├── profil/
│               └── settings/
├── Node-Agent/                Host-Agent (Rust, läuft auf Proxmox-Hosts)
│   ├── src/                   Rust-Quellen (main, dispatcher, commands, data, outbox, …)
│   ├── theprox-node-agent-x86_64  vorkompiliertes static Binary (Install-Output)
│   └── systemd/               theprox-agent.service
├── VM-Guest-Agent/            Rust-Crate (Linux/FreeBSD), läuft in VMs
│   ├── src/collect/           Collector (linux.rs, freebsd.rs, mod.rs)
│   └── theprox-vm-agent-x86_64  vorkompiliertes static Binary
└── Windows-VM-Guest-Agent/    Rust-Crate für Windows-VMs (+ Installer .exe)

---

RBAC

Berechtigung läuft pro Mandant (Tenant) über zwei Booleans, nicht über globale Rollen.

Ebene	Recht
is_superadmin (User-Flag)	Alles — überspringt sämtliche Tenant-/Node-Checks
can_write (pro Tenant)	Schreibend (impliziert can_read): Aktionen, Terminal, Jobs
can_read (pro Tenant)	Lesend: Nodes, VMs, Monitoring im Tenant-Scope
user_node_access	Optionale Per-User-Node-Whitelist innerhalb des Tenant-Scopes

RBAC-Helpers (server/auth/rbac.py): require_superadmin, require_read(), require_write(), plus check_node_scope / check_vm_scope. require_role(min) existiert als Backwards-Compat-Shim (viewer→read, operator/admin→write).

Tenant-Isolation: Nodes (1 Node → max. 1 Mandant) und VMID-Ranges werden Mandanten zugewiesen. Nutzer ohne is_superadmin sehen nur Ressourcen ihrer Mandanten; nicht zugewiesene Nodes sind nur für Superadmin sichtbar.

---

Agent

Der Agent ist ein Rust-Binary (Node-Agent/, ausgeliefert als statisches theprox-node-agent). Rust wurde als einzige kanonische Variante gewählt: Single-Binary-Deploy ohne venv/Python-Abhängigkeiten, geringerer Footprint. Die frühere Python-Variante wurde entfernt (Issue #2; Archiv: Git-Tag archive/python-node-agent). Deployment via Install-Script:

• Systemd-Service: theprox-agent
• Konfig: /etc/theprox-agent/agent.conf
• Logs: journalctl -u theprox-agent -f
• Neustart: systemctl restart theprox-agent

Verbindet sich ausgehend via WebSocket, führt Proxmox-Befehle lokal via pvesh, qm, pct aus und öffnet PTY-Terminals direkt auf dem Host. Lauscht zusätzlich auf TCP :9100 für VM-Guest-Agenten.

VM Guest-Agent

Optionaler Rust-Agent innerhalb der VMs (Linux/FreeBSD/Windows) für detaillierte In-Guest-Metriken und -Scans:

curl -fsSL http://SERVER:8765/vm-install/<TOKEN> | bash

• Konfig: /etc/theprox-vm-agent/agent.conf
• Verbindet ausgehend per TCP (JSON-Lines) zum Host-Agent (:9100)
• Sendet Metrics (15s) + Scans (5min)
• Binaries: VM-Guest-Agent/theprox-vm-agent-{arch} (static musl, vorkompiliert)

---

Sicherheitshinweise

• WebUI (:8080) nicht öffentlich exponieren — nur über VPN/Firewall zugänglich
• Agent-Endpoint (:8765) muss vom Proxmox-Host erreichbar sein (nur /ws/agent wird weitergeleitet)
• JWT-Secret mind. 32 Zeichen, zufällig generiert
• Agent-Tokens sind pro-Host einmalig und via UI rotierbar