👉 Direkt auf YouTube schauen und abonnieren:
Smart Home & More auf YouTube

Einleitung

Proxmox API Home Assistant Backup – in diesem Praxis‑Guide lernst du, wie du mithilfe der Proxmox API den Zustand deiner virtuellen Maschinen abfragst, Dashboards in Home Assistant erstellst und Backups automatisierst. Statt auf HACS setzt du dabei auf REST‑Sensoren und API‑Calls, um deine VMs sicher zu überwachen und zu sichern.

Vorbereitung in Proxmox – Benutzer, Token und Rechte einrichten

Bevor du in Home Assistant loslegen kannst, musst du Proxmox entsprechend vorbereiten.

API‑Benutzer und Token anlegen

Erstelle im Proxmox DataCenter einen neuen User (z. B. homeassistant) ohne Passwort, denn wir arbeiten mit API‑Tokens. Wähle als Realm pve und lege anschließend unter API Token einen neuen Token für diesen User an. Achte darauf, Privilege Separation zu deaktivieren. Kopiere dir den Token sofort, da er später nicht mehr angezeigt wird.

Rollen konfigurieren

Für den Zugriff auf VM‑Informationen und Backups benötigen wir passende Rollen:

• Lege eine neue Rolle (z. B. homeassistant-role) mit den Privilegien VM.Audit, Datastore.Audit und Datastore.AllocateSpace, VM.Backup an.
• Weise diese Rolle dem User auf den benötigten Pfaden zu: dem Node (/nodes/pve-lerch) und den VMs (/vms/*).

Diese granularen Berechtigungen sorgen dafür, dass Home Assistant lediglich die benötigten Daten abrufen und einen Proxmox API Home Assistant Backup auslösen darf.

Home Assistant konfigurieren – REST‑Sensoren anlegen

Im nächsten Schritt richten wir Home Assistant ein. Falls du noch keinen File Editor installiert hast, installiere diesen im Add-on Store von Home Assistant.

REST‑Sensor für VM‑Informationen

Über den YAML‑Eintrag rest: definieren wir einen Sensor, der regelmäßig einen GET‑Request an die Proxmox API sendet. Die URL lautet beispielsweise:

https://<proxmox-host>/api2/json/nodes/pve-larch/qemu

Als Header gibst du Authorization: PVEAPIToken=<user>@pve!<token-id>=<token> an. Im value_template kannst du die JSON‑Antwort weiterverarbeiten und die Daten in Attributen speichern.

  - resource: https://192.168.101.69:8006/api2/json/nodes/pvelerch/qemu
    method: GET
    headers:
      Authorization: "PVEAPIToken=homeassistant@pve!proxmox=be729a21-e76b-430b-84bf-40d096d035a6"
    verify_ssl: false
    scan_interval: 10
    sensor:
      - name: "PVELerch VM Raw"
        unique_id: pvelerch_vm_raw
        value_template: "OK"
        json_attributes:
          - data

Vergiss nicht, Home Assistant neu zu starten, damit der Sensor angelegt wird. Anschließend siehst du eine Liste aller VMs als JSON‑Attribut, inklusive ihrer Namen, IDs und Status.

REST‑Sensor für LXC‑Container

Für LXC‑Container wiederholst du den Sensor mit dem Endpunkt .../lxc. Denke daran, dass nicht alle API‑Attribute identisch sind – die Belegung des Festplattenspeichers (disk-usage) steht nur bei Containern zur Verfügung.

  - resource: https://192.168.101.69:8006/api2/json/nodes/pvelerch/lxc
    method: GET
    headers:
      Authorization: "PVEAPIToken=homeassistant@pve!proxmox=be729a21-e76b-430b-84bf-40d096d035a6"
    verify_ssl: false
    scan_interval: 10
    sensor:
      - name: "PVELerch LXC Raw"
        unique_id: pvelerch_lxc_raw
        value_template: "OK"
        json_attributes:
          - data

Hier nochmal beide Rest Sensoren für die Configuration.Yaml. Beachte, dass am Anfang einmal „rest:“ stehen muss.

rest:
  - resource: https://192.168.101.69:8006/api2/json/nodes/pvelerch/qemu
    method: GET
    headers:
      Authorization: "PVEAPIToken=homeassistant@pve!proxmox=be729a21-e76b-430b-84bf-40d096d035a6"
    verify_ssl: false
    scan_interval: 10
    sensor:
      - name: "PVELerch VM Raw"
        unique_id: pvelerch_vm_raw
        value_template: "OK"
        json_attributes:
          - data
          
  - resource: https://192.168.101.69:8006/api2/json/nodes/pvelerch/lxc
    method: GET
    headers:
      Authorization: "PVEAPIToken=homeassistant@pve!proxmox=be729a21-e76b-430b-84bf-40d096d035a6"
    verify_ssl: false
    scan_interval: 10
    sensor:
      - name: "PVELerch LXC Raw"
        unique_id: pvelerch_lxc_raw
        value_template: "OK"
        json_attributes:
          - data

Dashboard gestalten – Markdown‑Karte für VM‑Übersicht

Um die Daten ansprechend zu visualisieren, kannst du eine Markdown‑Karte in deinem Home‑Assistant‑Dashboard einfügen. Im Template liest du die Attribute der Sensoren aus und listest jede VM mit Name, Uptime, Status und, bei LXC‑Containern, prozentual belegtem Speicherplatz auf.

{% set vms = state_attr('sensor.pvelerch_vm_raw', 'data') or [] %}
{% set lxcs = state_attr('sensor.pvelerch_lxc_raw', 'data') or [] %}

## 🖥️ Virtuelle Maschinen (QEMU)

{% for vm in vms | sort(attribute='vmid') %}
  {% set days = vm.uptime // 86400 %}
  {% set hours = (vm.uptime % 86400) // 3600 %}
  {% set minutes = (vm.uptime % 3600) // 60 %}
  {% if days > 0 %}
    {% set uptime_str = days ~ 'd ' ~ hours ~ 'h' %}
  {% else %}
    {% set uptime_str = hours ~ 'h ' ~ minutes ~ 'm' %}
  {% endif %}
- **{{ vm.vmid }}** | {{ vm.name }} | Uptime: {{ uptime_str }} | {{ "🟢" if vm.status == "running" else "🔴" }}
{% endfor %}

## 📦 LXC-Container

{% for lxc in lxcs | sort(attribute='vmid') %}
  {% set days = lxc.uptime // 86400 %}
  {% set hours = (lxc.uptime % 86400) // 3600 %}
  {% set minutes = (lxc.uptime % 3600) // 60 %}
  {% if days > 0 %}
    {% set uptime_str = days ~ 'd ' ~ hours ~ 'h' %}
  {% else %}
    {% set uptime_str = hours ~ 'h ' ~ minutes ~ 'm' %}
  {% endif %}
- **{{ lxc.vmid }}** | {{ lxc.name }} | Disk: {{ ((lxc.disk / lxc.maxdisk) * 100) | round(1) if lxc.maxdisk and lxc.maxdisk > 0 else 'n/a' }} % | Uptime: {{ uptime_str }} | {{ "🟢" if lxc.status == "running" else "🔴" }}
{% endfor %}

So siehst du live, wenn eine VM gestoppt wird oder startet. Über Automationen kannst du sogar Benachrichtigungen verschicken, wenn sich der Status ändert. Achte darauf, dass du die Entitäten auf deine Entitätsnamen anpasst.

sensor.pvelerch_vm_raw

sensor.pvelerch_lxc_raw

Monitoring & Test – Live‑Überwachung von VMs

Teste deine Konfiguration, indem du eine VM in Proxmox stoppst und wieder startest. Die Änderungen sollten in der Markdown‑Karte nach dem nächsten Scan‑Intervall sichtbar sein. Dieses Szenario zeigt, wie zuverlässig die REST‑API im Zusammenspiel mit Home Assistant funktioniert.

Backups per API auslösen

Eines der mächtigsten Features der Proxmox API ist die Möglichkeit, Backups zu starten.

Rollen erweitern

Erweitere deine Rolle um die Berechtigungen VM.Backup und Datastore.AllocateSpace, damit der User Backups auslösen darf ( haben wir schon im ersten Schritt getan ). Vergiss nicht, auch den Storage‑Pfad (/storage) mit dieser Rolle zu verknüpfen.

REST‑Command für VZDump

In Home Assistant legst du unter rest_command: einen neuen Befehl an. Die URL endet diesmal auf /vzdump, die Methode ist POST, und als Payload übergibst du Parameter wie vmid, mode (z. B. snapshot), storage und compress.

rest_command:
  pvelerch_backup:
    url: "https://192.168.101.69:8006/api2/json/nodes/pvelerch/vzdump"
    method: POST
    headers:
      Authorization: "PVEAPIToken=homeassistant@pve!proxmox=be729a21-e76b-430b-84bf-40d096d035a6"
      Content-Type: "application/x-www-form-urlencoded"
    payload: "vmid=100,101,104,106,108,112,113,114,116,119,102,103,105&mode=snapshot&storage=PBS&compress=zstd"
    verify_ssl: false

Ein Aufruf dieses REST‑Commands startet sofort den Backup‑Job in Proxmox. Über die Home‑Assistant‑Entwicklerwerkzeuge kannst du den Befehl testen. In einer Automation oder auf einem Button platziert, kannst du einen Proxmox API Home Assistant Backup sogar zeit‑ oder ereignisgesteuert auslösen.

Fazit & Ausblick

Mit ein wenig Konfigurationsaufwand lässt sich die Proxmox API hervorragend in Home Assistant integrieren. Du kannst den Zustand deiner VMs und LXC‑Container überwachen, in Dashboards visualisieren und sogar Backups per Knopfdruck starten. Nutze diese Lösung als Grundlage für weitere Automatisierungen, zum Beispiel um Benachrichtigungen zu verschicken oder externe Dienste einzubinden.

Wenn du mehr über Energie‑Management erfahren willst, schau dir auch unseren Beitrag zur EVCC‑Einbindung in Home Assistant an. Für Einsteiger in Proxmox empfehlen wir den Artikel Proxmox Grundinstallation Schritt für Schritt.

Link‑Liste

• Proxmox API Dokumentation – Die offizielle Referenz zu allen Endpunkten.
• Home Assistant REST Sensor (Documentation) – Informationen zur REST‑Sensor‑Integration.
• EVCC‑Add‑on Installation – Video/Beitrag zur Installation des EVCC‑Add‑ons.