Was ist Home Assistant OS (HAOS)?

Home Assistant Operating System (HAOS) ist ein speziell entwickeltes, minimales Linux-Betriebssystem, das aus einer Hardware oder einer virtuellen Maschine ein dediziertes Smart-Home-Steuergerät („Appliance“) macht.

Im Gegensatz zu einer reinen Software-Installation verwaltet HAOS das gesamte System selbstständig. Der größte Vorteil von HAOS ist der integrierte Supervisor: Er ermöglicht die Installation von Erweiterungen (Add-ons) wie Zigbee2MQTT, Node-RED, Mosquitto Broker oder ESPHome mit nur einem Klick direkt aus der Home-Assistant-Oberfläche.

Darüber hinaus kümmert sich HAOS automatisch um Betriebssystem- und Core-Updates, bietet ein nahtloses Backup-System für das Gesamtsystem und sorgt für eine einfache Anbindung von Smart-Home-Hardware (wie USB-Zigbee-Sticks). Es ist die von den Entwicklern empfohlene Installationsmethode für den wartungsarmen und stabilen Betrieb.

Installation

Englische Anleitung: https://www.home-assistant.io/installation/generic-x86-64

• Boote den MiniPC mit einem Ubuntu Desktop System
  • Download Ubuntu Desktop
• Lade das neuste „Generic x86-64“ Image herunter („haos_generic-x86-64-**.*.img.xz“)
  • https://github.com/home-assistant/operating-system/releases/
• Öffne eine Shell
• Starte das folgende Kommando
  • sudo xzcat /pfad/zur/haos_generic-x86-64-X.X.img.xz | sudo dd of=/dev/sda bs=4M status=progress
• Danach ist auf „sda“ ein komplettes HAOS installiert mit dem gleich gebootet wird.

HomeAssistant einrichten

Siehe HomeAssistant Ersteinrichtung

Web-Oberfläche von Home Assistant aufrufen

1. Öffne einen Browser und rufe die IP Adresse der HomeAssistant Installation auf:
   • http://<VM-IP-ADRESSE>:8123
   • oder [http://homeassistant.local:8123](http://homeassistant.local:8123)
2. Richte dein Administrator-Konto ein und schließe die Ersteinrichtung ab.

MQTT Installation

Home Assistant stellt von Haus aus lediglich die Schnittstelle bereit, um mit einem MQTT-Broker zu kommunizieren. Der Broker selbst – die Zentrale, die den Nachrichtenverkehr verwaltet – muss zuerst eingerichtet werden.

Der einfachste Weg ist die Installation des offiziellen Mosquitto Brokers direkt als Add-on in Home Assistant OS:

In 3 Schritten zum funktionierenden MQTT Broker:

1. Add-on installieren:
   • Gehe in Home Assistant auf „Einstellungen / Apps / App installieren“ (unten rechts).
   • Suche nach Mosquitto broker, klicke darauf und wähle Installieren.
   • Aktiviere den Schalter Starten beim Booten und klicke auf Starten.
2. MQTT-Benutzer anlegen (Empfohlen):
   • Gehe auf „Einstellungen / Personen / Benutzer“ (falls nicht sichtbar: Profilbild unten links anklicken und Erweiterter Modus aktivieren).
   • Erstelle einen neuen Benutzer (z. B. Name: mqtt-user) mit einem sicheren Passwort. Dieser wird von deinen Smart-Home-Geräten (z. B. ESP32, Tasmota, Zigbee2MQTT) für die Anmeldung verwendet.
3. Integration aktivieren:
   • Gehe auf „Einstellungen / Geräte & Dienste„.
   • Oft wird MQTT dort bereits automatisch als Entdeckt angezeigt. Klicke auf Einrichten.
   • Falls nicht: Klicke unten rechts auf Integration hinzufügen, suche nach MQTT und folge den Anweisungen.

Die Installation von Home Assistant Operating System (HAOS) auf Proxmox VE als virtuelle Maschine (VM) gilt als der Goldstandard für ein flexibles Smart Home. Du erhältst damit die volle Funktionalität von HAOS (inklusive Add-on-Store, Supervisor und automatischen Updates), während du gleichzeitig Schnappschüsse (Snapshots) und Backups des gesamten Systems in Proxmox erstellen kannst.

Der eleganteste Weg zur Installation führt über die Proxmox VE Helper-Scripts der Community.

Was ist Proxmox VE?

Proxmox Virtual Environment (PVE) ist eine quelloffene (Open-Source) Plattform für Server-Virtualisierung. Sie basiert auf Debian Linux und nutzt KVM (Kernel-based Virtual Machine) für vollwertige virtuelle Maschinen sowie LXC für leichtgewichtige Container.

Kurz gesagt: Proxmox erlaubt es dir, auf einer einzigen physischen Hardware mehrere unabhängige Betriebssysteme parallel zu betreiben. Für Home Assistant ist das ideal, weil HAOS als isolierte VM mit eigenen Ressourcen läuft und du über Proxmox jederzeit schnelle Sicherungspunkte (Snapshots) oder Backups deines gesamten Smart Homes erstellen kannst.

Was ist Home Assistant OS (HAOS)?

Home Assistant Operating System (HAOS) ist ein speziell entwickeltes, minimales Linux-Betriebssystem, das aus einer Hardware oder einer virtuellen Maschine ein dediziertes Smart-Home-Steuergerät („Appliance“) macht.

Im Gegensatz zu einer reinen Software-Installation verwaltet HAOS das gesamte System selbstständig. Der größte Vorteil von HAOS ist der integrierte Supervisor: Er ermöglicht die Installation von Erweiterungen (Add-ons) wie Zigbee2MQTT, Node-RED, Mosquitto Broker oder ESPHome mit nur einem Klick direkt aus der Home-Assistant-Oberfläche.

Darüber hinaus kümmert sich HAOS automatisch um Betriebssystem- und Core-Updates, bietet ein nahtloses Backup-System für das Gesamtsystem und sorgt für eine einfache Anbindung von Smart-Home-Hardware (wie USB-Zigbee-Sticks). Es ist die von den Entwicklern empfohlene Installationsmethode für den wartungsarmen und stabilen Betrieb.

Voraussetzungen

• Ein einsatzbereiter Proxmox VE Host (empfohlen: Proxmox VE 8.x)
• Zugewiesener Speicherplatz auf dem Proxmox-Node (mind. 32 GB NVMe/SSD empfohlen)
• Internetverbindung des Proxmox-Hosts zum Herunterladen des HAOS-Images

Installation

Proxmox Shell öffnen

Zugriff auf die Node-Konsole.

1. Melde dich im Web-Interface deines Proxmox VE Servers an (https://<PROXMOX-IP>:8006).
2. Wähle im linken Menübaum deinen Node (z. B. pve) aus.
3. Klicke im Menü oben rechts oder in der Seitennavigation auf >_ Shell.

Helper-Script starten

Führt den automatischen VM-Builder aus – Kopiere folgenden Befehl, füge ihn in die Proxmox-Shell ein und drücke Enter:

Bash

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/haos-vm.sh)"

Hinweis: Das Skript stammt aus dem etablierten Open-Source-Projekt Proxmox VE Helper-Scripts (Community Edition).

Installations-Assistent durchlaufen

Ressourcen und Einstellungen definieren.

Das Skript führt dich durch ein interaktives Menü:

1. Bestätige die Abfrage „Create a Home Assistant OS VM?“ mit Yes (Enter).
2. Wähle zwischen [Default] und [Advanced]:
   • Default Settings (empfohlen): Erstellt automatisch eine VM mit 2 CPU-Kernen, 4 GB RAM, 32 GB Speicherplatz und UEFI-Bios.
   • Advanced Settings: Ermöglicht die Anpassung von VM-ID, CPU-Kernen, RAM, Storage-Pool und VLANs.
3. Das Skript lädt nun das neueste offizielle HAOS-KVM-Image herunter, konfiguriert die VM und startet sie automatisch.

Hardware an VM durchreichen

USB-Passthrough für Zigbee-, Z-Wave- oder Bluetooth-Sticks.

Falls du USB-Hardware (z. B. Sonoff Zigbee Dongle, ConBee II, Z-Wave-Stick) nutzt:

1. Wähle die neu erstellte HomeAssistant VM in Proxmox aus.
2. Gehe auf Hardware ➔ Hinzufügen ➔ USB-Gerät.
3. Wähle „USB-Hersteller/Geräte-ID nutzen“ oder „USB-Port nutzen“ und wähle deinen Stick aus.
4. Klicke auf Hinzufügen. Der Stick wird direkt in HAOS verfügbar.

HomeAssistant einrichten

Jetzt kann die Einrichtung von HomeAssistant wie gewoht über das Webinterface erfolgen. Die IP Adresse kann man leicht über die Console erfahren.

Wichtige Proxmox-Tipps für HomeAssistant

• Snapshots vor Updates: Erstelle vor größeren HomeAssistant-Updates in Proxmox unter VM ➔ Snapshots einen Wiederherstellungspunkt. Bei Problemen kannst du das gesamte System innerhalb weniger Sekunden zurückrollen.
• Proxmox Backups (PBS oder Lokal): Richte unter Datacenter ➔ Backup einen automatischen Zeitplan ein (z. B. 1x wöchentlich nachts), um die gesamte VM im laufenden Betrieb extern zu sichern.
• Feste IP-Adresse: Vergebe im Router (z. B. FRITZ!Box) eine feste IP-Adresse für die MAC-Adresse der VM, damit Home Assistant im Netzwerk immer unter derselben Adresse erreichbar bleibt.

Bilder

Docker installieren

Falls Docker auf dem Ubuntu-System noch nicht eingerichtet ist, lässt es sich über das offizielle Repository installieren:

# Paketlisten aktualisieren und Voraussetzungen installieren
sudo apt update && sudo apt install -y ca-certificates curl gnupg lsb-release

# Offiziellen Docker GPG-Schlüssel hinzufügen
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Repository einrichten
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker Engine & Compose Plugin installieren
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Aktuellen Benutzer zur docker-Gruppe hinzufügen (vermeidet sudo bei Docker-Befehlen)
sudo usermod -aG docker $USER
newgrp docker

Verzeichnisstruktur und Mosquitto-Konfiguration erstellen

Erstellen Sie die benötigten Ordner für die persistenten Daten von Home Assistant und Mosquitto:

sudo mkdir -p /home/homeassistant/docker/config
sudo mkdir -p /home/homeassistant/docker/mosquitto/config \
              /home/homeassistant/docker/mosquitto/data \
              /home/homeassistant/docker/mosquitto/log

# D-Bus Verzeichnis auf dem Host sicherstellen (wird von Home Assistant genutzt)
sudo mkdir -p /run/dbus

# Besitzrechte für das Arbeitsverzeichnis an den aktuellen Benutzer übertragen
sudo chown -R $USER:$USER /home/homeassistant/docker

cd /home/homeassistant/docker

Die Configdatei „mosquitto/config/mosquitto.conf“ für Mosquitto erstellen, und mit folgenden Code befüllen:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwords
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

Schreibrechte anpassen:

sudo chown -R 1883:1883 /home/homeassistant/docker/mosquitto

Docker Compose einrichten und Container starten

Anlegen der Datei „docker-compose.yml“ mit folgendem Inhalt:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - /home/homeassistant/docker/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:latest
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - /home/homeassistant/docker/mosquitto/config:/mosquitto/config
      - /home/homeassistant/docker/mosquitto/data:/mosquitto/data
      - /home/homeassistant/docker/mosquitto/log:/mosquitto/log

MQTT-Benutzer anlegen & Stack starten

Wechselne in das Arbeitsverzeichnis und starte zuerst ausschließlich den Mosquitto-Container, um den MQTT-Benutzer anzulegen:

cd /home/homeassistant/docker
docker compose up -d mosquitto

Legen nun den Benutzer für die MQTT-Geräte und Home Assistant an (z. B. homeassistant). Verwende bewusst nicht den Parameter -c, damit bestehende Konfigurationen nicht überschrieben werden:

docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwords homeassistant

Sichere die Dateirechte der neu erstellten Passwort-Datei ab, um Warnungen und Berechtigungsfehler im Mosquitto-Log zu vermeiden:

sudo chmod 600 /home/homeassistant/docker/mosquitto/config/passwords
sudo chown 1883:1883 /home/homeassistant/docker/mosquitto/config/passwords

Und anschließend den gesamten Stack starten:

docker compose up -d

Home Assistant Ersteinrichtung & MQTT-Integration

• Öffne im Browser http://<IP-DEINES-SERVERS>:8123.
• Erstelle das Administrator-Konto und schließe die Ersteinrichtung ab.
  • Erstellen eines Admin Kontos
  • Wählen des Standortes
  • Erlaubnis zum Teile anonymisierte Daten
• Navigiere zu Einstellungen → Geräte & Dienste → Integration hinzufügen.
• Suchen nach MQTT und wählen Sie es aus.
• Trage die Verbindungsdaten ein:
  • Broker: localhost (oder die IP-Adresse des Ubuntu-Servers)
  • Port: 1883
  • Benutzername: homeassistant
  • Passwort: Das in Schritt 4 vergebene Passwort

MQTT-Benutzer ändern und hinzufügen

Im Smart Home ist es ratsam, verschiedenen Geräten eigene Zugangsdaten zuzuweisen oder Passwörter bei Bedarf anzupassen. Der Mosquitto-Broker erlaubt das Anlegen mehrerer Benutzer sowie das Ändern bestehender Passwörter.

Weitere Benutzer hinzufügen

Um einen neuen Benutzer (z. B. tasmota für deine Steckdosen) anzulegen, führe folgenden Befehl aus:

docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwords tasmota

Passwörter bestehender Benutzer ändern

Das Ändern eines Passworts für einen bereits existierenden Benutzer (z. B. homeassistant) erfolgt mit demselben Befehl:

docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwords homeassistant

Warum zwei Docker-Container? Das Zusammenspiel von Home Assistant & Mosquitto

Ein zentrales Prinzip von Docker lautet: Ein Container pro Aufgabe (Single Responsibility Principle). Anstatt alle Smart-Home-Dienste in ein einzelnes, träges System zu packen, teilen wir die Aufgaben auf zwei spezialisierte Container auf.

Die Rollen der beiden Container

• Mosquitto (Der Postbote)
  • Mosquitto ist ein extrem leichtgewichtiger MQTT-Broker. Seine einzige Aufgabe ist das schnelle, zuverlässige Empfangen und Weiterleiten von Nachrichten im Netzwerk. Er kennt keine Smart-Home-Logiken, Szenen oder Dashboards, sondern nimmt Telegramme von Geräten entgegen und verteilt sie an alle Abonnenten.
• Home Assistant (Das Gehirn)
  • Home Assistant ist die smarte Schaltzentrale. Hier laufen die Automatisierungen, die Benutzeroberfläche (Dashboard) und die Logik. Home Assistant wertet Sensorwerte aus, führt Zeitpläne aus und steuert deine Geräte.

Wie die Container zusammenarbeiten

Die Kommunikation zwischen den Komponenten folgt dem Publish/Subscribe-Prinzip (Veröffentlichen und Abonnieren):

[ Tasmota-Steckdose ]  ---(1. Schalterzustand senden)--->  [ Mosquitto Broker ]
                                                                  |
                                                    (2. Nachricht weiterleiten)
                                                                  v
[ Dashboard / User ]   <---(3. Status anzeigen)-----------  [ Home Assistant ]

• Ein Gerät sendet Daten (Publish): Wenn du beispielsweise eine Tasmota-Steckdose manuell einschaltest, sendet das Gerät eine MQTT-Nachricht (z. B. stat/steckdose1/POWER = ON) an den Mosquitto-Container auf Port 1883.
• Mosquitto verteilt die Daten: Mosquitto prüft, wer sich für das Thema (Topic) stat/steckdose1/POWER interessiert.
• Home Assistant empfängt Daten (Subscribe): Da Home Assistant über die MQTT-Integration beim Mosquitto-Broker angemeldet ist und das Thema abonniert hat, empfängt es die Nachricht sofort und aktualisiert den Schalterstatus auf dem Dashboard.
• Befehle senden (Der umgekehrte Weg): Klickst du in Home Assistant auf „Ausschalten“, schickt Home Assistant eine Nachricht (cmnd/steckdose1/POWER = OFF) an Mosquitto. Mosquitto reicht diesen Befehl an die Steckdose weiter, die daraufhin das Relais öffnet.

Die Vorteile dieser Trennung

• Unabhängigkeit
  • Wenn Home Assistant z. B. für ein Update neu gestartet wird, läuft der Mosquitto-Broker ununterbrochen weiter. Deine MQTT-Geräte verlieren nie die Verbindung zum Broker und können weiterhin Nachrichten puffern.
• Leistung & Stabilität
  • Mosquitto ist in C geschrieben, extrem ressourcenschonend und arbeitet hochparallel. Es verbraucht kaum Arbeitsspeicher und entlastet Home Assistant spürbar.
• Flexibilität
  • Du kannst jederzeit weitere Systeme (wie z. B. Node-RED, eigene Python-Scripte oder WLED-Monitore) an denselben Mosquitto-Broker anbinden, ohne die Konfiguration von Home Assistant anpassen zu müssen.

FAQ

HomeAssistant Admin Passwort vergessen

Um das Passwort des HomeAssistant Admin zu löschen, muss man folgende Schritte durchführen:

• auf des Ubuntu-Server einloggen (ssh)
• In das Arbeitsverzeichnis wechseln
  • cd /home/homeassistant/docker
• Home Assistant stoppen
  • docker compose stop homeassistant
• Auth-Dateien im Config-Ordner sichern & löschen
  • Navigiere in den internen .storage-Ordner von Home Assistant. Dort verwaltet Home Assistant die Benutzerkonten:
    • cd /home/homeassistant/docker/config/.storage
  • Lösche die Dateien für die Benutzerverwaltung und Authentifizierung (oder benenne sie zur Sicherheit um):
    • sudo mv auth auth.bak
    • sudo mv onboarding onboarding.bak
    • sudo mv auth_provider.homeassistant auth_provider.homeassistant.bak
• Home Assistant Container wieder starten
  • cd /home/homeassistant/docker
  • docker compose start homeassistant
• Neuen Admin-Account im Browser anlegen:
  • Öffne im Browser erneut http://<IP-DEINES-SERVERS>:8123.
  • Home Assistant begrüßt dich nun wieder mit dem Welcome- / Ersteinrichtungs-Bildschirm.
  • Erstelle einen neuen Administrator-Benutzer (du kannst denselben Benutzernamen wie vorher verwenden).
  • Nach dem Abschließen des Assistenten gelangst du wieder auf dein gewohntes Dashboard. Alle deine Einstellungen, Integrationen, Skripte und Karten sind weiterhin vollständig vorhanden.