Home Assistant Container ist die Docker-basierte Installationsvariante der populären Open-Source-Smart-Home-Zentrale Home Assistant. Im Gegensatz zu Home Assistant OS (HAOS) läuft hier kein Supervisor und es gibt keine Ein-Klick-Add-ons - dafür bekommst du einen schlanken, voll kontrollierbaren Container, den du wie jeden anderen Dienst per docker compose betreibst. Genau richtig für alle, die bereits einen Linux-Server mit Docker laufen haben und ihr Smart Home lokal, ohne Cloud steuern wollen. In dieser Anleitung richtest du Home Assistant von Grund auf ein: compose.yaml, Onboarding, erste Integrationen, eine Automatisierung sowie Update- und Backup-Workflow.

Kurzfassung: Verzeichnis anlegen, compose.yaml mit dem Image ghcr.io/home-assistant/home-assistant:stable, network_mode: host und Volume ./config erstellen, dann starten und im Browser einrichten.

mkdir -p ~/homeassistant/config && cd ~/homeassistant
# compose.yaml anlegen (siehe Schritt 2), dann:
docker compose up -d
# Onboarding im Browser: http://SERVER-IP:8123

Voraussetzungen

Bevor es losgeht, sollte deine Umgebung stehen. Home Assistant Container ist genügsam - eine dedizierte GPU brauchst du nicht.

Linux-Server mit Docker und dem Plugin Docker Compose (getestet mit Debian 12 oder Ubuntu 24.04). Ein Raspberry Pi 4/5, ein Mini-PC oder ein vorhandener Heimserver reichen völlig.
RAM: Die offizielle Doku nennt für die Container-Variante keine festen Mindestwerte. Als Richtwert gilt der HAOS-Wert von mindestens 2 GB RAM; für eine kleine Installation auf einem Pi 4/5 passt das gut.
GPU: Für Home Assistant selbst ist keine GPU erforderlich. Erst wenn du später rechenintensive Zusatzdienste in eigenen Containern betreibst (z. B. lokales LLM-Serving oder Bildverarbeitung), wird eine GPU plus das nvidia-container-toolkit relevant - das ist aber nicht Teil von Home Assistant.
Netzwerk: Eine feste IP oder DHCP-Reservierung für den Server ist sinnvoll, damit du die Web-UI immer unter derselben Adresse erreichst.
Optional: ein USB-Stick für Zigbee oder Z-Wave sowie eine Domain plus Reverse-Proxy, falls du von aussen zugreifen willst.

Docker und Compose sind installiert, wenn folgende Befehle Versionen ausgeben:

docker --version
docker compose version

Schritt 1: Projektverzeichnis anlegen

Lege ein eigenes Verzeichnis für den Stack an. Darin liegen später sowohl die compose.yaml als auch das persistente config-Verzeichnis, in dem Home Assistant alle Daten ablegt.

mkdir -p ~/homeassistant/config
cd ~/homeassistant

Das Unterverzeichnis config ist das Herzstück deiner Installation: Hier landen Konfiguration, Datenbank, Automatisierungen und Geheimnisse. Wer dieses Verzeichnis sichert, sichert die komplette Home-Assistant-Instanz.

Schritt 2: compose.yaml erstellen

Erstelle im Verzeichnis ~/homeassistant die Datei compose.yaml. Das folgende Beispiel entspricht dem offiziellen Setup für die Container-Variante: Image stable, persistentes ./config-Volume, network_mode: host für die Auto-Discovery, Zeitzone und ein robuster Neustart-Modus.

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

Was die wichtigsten Zeilen bedeuten:

image: Das offizielle Image. Der Tag stable liefert die jeweils aktuelle stabile Version. Alternativ kannst du beta, dev oder eine feste Version wie 2026.5.4 pinnen - feste Tags machen Updates planbarer.
volumes: ./config:/config hält alle Daten außerhalb des Containers persistent. /etc/localtime übernimmt die Host-Zeit, /run/dbus wird für Bluetooth und dbus benötigt.
network_mode: host: Pflicht für die automatische Geräteerkennung über mDNS, SSDP und UPnP. Damit findet Home Assistant viele Geräte von selbst. Die Web-UI läuft dann direkt auf Port 8123 des Hosts.
privileged: true: Steht so im offiziellen Compose-Beispiel und gibt dem Container den nötigen Hardware- und USB-Zugriff. Wer das vermeiden möchte, reicht stattdessen gezielt einzelne devices bzw. cap_add durch (siehe Schritt 6).
TZ: Setze die Zeitzone, sonst stimmen Zeitstempel und zeit- bzw. sonnenbasierte Automationen nicht.

Schritt 3: Container starten

Starte den Stack im Hintergrund:

docker compose up -d

Beim ersten Start zieht Docker das Image und Home Assistant initialisiert das config-Verzeichnis. Das kann ein bis zwei Minuten dauern. Den Fortschritt verfolgst du mit:

docker logs -f homeassistant

Sobald in den Logs eine Zeile wie Home Assistant initialized erscheint, ist die Instanz bereit. Mit Strg+C verlässt du die Live-Logs wieder, ohne den Container zu stoppen.

Schritt 4: Web-UI und Ersteinrichtung (Onboarding)

Oeffne im Browser http://SERVER-IP:8123 (ersetze SERVER-IP durch die IP deines Servers). Es gibt keine Standard-Zugangsdaten - stattdessen führt dich das Onboarding durch die Ersteinrichtung:

Lege deinen Admin-Account an (Name, Benutzername, sicheres Passwort). Diese Daten gibt es nur bei dir, also gut aufbewahren.
Vergib einen Namen für dein Zuhause und setze den Standort. Der Standort ist wichtig für Sonnenauf- und -untergang und damit für viele Automationen.
Stelle Einheiten und Zeitzone ein (passend zur TZ aus der compose.yaml).
Am Ende zeigt Home Assistant bereits automatisch erkannte Geräte an. Dank network_mode: host tauchen hier oft schon Fernseher, Drucker, Mediaplayer oder smarte Steckdosen auf.

Danach landest du im Dashboard (Lovelace), der zentralen Oberfläche von Home Assistant.

Schritt 5: Integrationen, Geräte und erste Automatisierung

Eine Integration verbindet Home Assistant mit einem Gerät oder Dienst. Jedes Gerät stellt eine oder mehrere Entitäten bereit (z. B. Schalter, Sensor, Licht) - das sind die Bausteine, mit denen du steuerst und automatisierst.

Integration hinzufügen

Gehe zu Einstellungen > Geraete & Dienste. Unter Entdeckt findest du die per Auto-Discovery gefundenen Geräte - ein Klick auf Konfigurieren bindet sie ein. Fehlt etwas, fügst du es über Integration hinzufügen manuell hinzu und suchst nach Hersteller oder Protokoll.

Erste Automatisierung anlegen

Eine Automatisierung besteht immer aus drei Teilen: Auslöser (wann), Bedingung (nur wenn) und Aktion (was passiert). Beispiel: Beim Sonnenuntergang das Wohnzimmerlicht einschalten.

Gehe zu Einstellungen > Automatisierungen & Szenen und klicke Automatisierung erstellen > Neue Automatisierung.
Auslöser: Typ Sonne, Ereignis Sonnenuntergang.
Bedingung (optional): z. B. nur, wenn jemand zu Hause ist.
Aktion: Gerät bzw. Entität auswählen und Aktion Einschalten setzen.
Speichern und Namen vergeben - fertig.

So baust du Schritt für Schritt komplexere Abläufe, ganz ohne externe Cloud.

Schritt 6: USB-Sticks und Add-on-Ersatz (Zigbee, Z-Wave, MQTT)

Wichtig zu wissen: Add-ons gibt es nur unter HAOS. In der Container-Variante betreibst du Dienste wie Mosquitto (MQTT), ESPHome, Zigbee2MQTT oder Z-Wave JS UI als eigene Docker-Container und verbindest sie über das Netzwerk mit Home Assistant.

USB-Stick durchreichen

Für Zigbee- oder Z-Wave-Sticks reichst du das USB-Gerät in den Container durch. Nutze unbedingt den stabilen by-id-Pfad statt /dev/ttyUSB0 - letzterer kann sich nach Reboot oder USB-Wechsel ändern.

# stabilen Pfad ermitteln
ls -l /dev/serial/by-id/

services:
  homeassistant:
    devices:
      - /dev/serial/by-id/usb-XXXXX:/dev/ttyUSB0

Den ermittelten by-id-Pfad trägst du anstelle von usb-XXXXX ein. Wer privileged: true vermeiden möchte, kombiniert diesen devices-Eintrag mit gezielten cap_add-Rechten und stellt den Hardware-Zugriff so selbst sicher.

Schritt 7: Reverse-Proxy und HTTPS

Wenn Home Assistant hinter einem Reverse-Proxy (z. B. Nginx oder Traefik) laufen soll, musst du das in der Konfiguration freischalten - sonst verweigert Home Assistant den Zugriff oder loggt falsche Client-IPs. Ergänze in ./config/configuration.yaml:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.16.0.0/12   # IP/Subnetz des Proxys (Netzadresse, kein Host)

Trage unter trusted_proxies die Netzadresse deines Proxy-Netzes ein (z. B. 192.168.1.0/24), nicht die einzelne Host-IP. Soll Home Assistant im Bridge-Modus statt mit Host-Netz laufen (typisch hinter einem Proxy), mappst du den Port explizit und entfernst network_mode: host - beachte aber, dass die Auto-Discovery dann wegfällt:

services:
  homeassistant:
    ports:
      - "8123:8123"
    # network_mode: host dann entfernen (Auto-Discovery faellt weg)

Nach jeder Änderung an der configuration.yaml prüfst du die Konfiguration, bevor du neu startest:

docker exec homeassistant python -m homeassistant --script check_config
docker compose restart homeassistant

Schritt 8: Update- und Backup-Workflow

In der Container-Variante sind Updates und Backups manuell - dafür hast du sie voll in der Hand.

Update durchführen

Prüfe vor jedem Update die Release Notes auf Breaking Changes und lege ein Backup an. Dann:

docker compose pull homeassistant
docker compose up -d

docker compose up -d ersetzt den alten Container durch einen mit dem neuen Image; deine Daten bleiben dank des ./config-Volumes erhalten. Der Tag stable kann größere Versionssprünge bringen - pinnst du eine feste Version, sind Updates besser kalkulierbar.

Backup anlegen

Da integrierte Backups nur HAOS bietet, sicherst du das gesamte config-Verzeichnis selbst - am besten vor jedem Update. Stoppe den Container kurz für ein konsistentes Backup:

docker compose stop homeassistant
tar czf ha-backup-$(date +%F).tar.gz config
docker compose start homeassistant

Bewahre die Archive außerhalb des Servers auf (z. B. NAS oder Offsite-Storage). Im Ernstfall stellst du die Instanz wieder her, indem du das config-Verzeichnis zurückspielst und den Stack neu startest.

Troubleshooting

Die häufigsten Stolpersteine und ihre Lösung:

Problem	Ursache & Lösung
Geräte werden nicht automatisch gefunden	`network_mode: host` fehlt. Ohne Host-Netz bricht die Discovery über mDNS/SSDP/UPnP. Im Bridge-Modus Port mappen und Discovery manuell konfigurieren.
Add-on lässt sich nicht installieren	Add-ons gibt es nur unter HAOS. Mosquitto, ESPHome, Zigbee2MQTT oder Z-Wave JS UI als eigene Container betreiben und über das Netzwerk anbinden.
Zigbee/Z-Wave-Stick nach Reboot weg	`/dev/ttyUSB0` ist nicht stabil. Stattdessen `/dev/serial/by-id/` verwenden.
Falsche Zeitstempel, Automationen feuern falsch	`TZ` nicht oder falsch gesetzt. `TZ` in der compose.yaml und den Standort im Onboarding korrekt setzen.
Zugriff hinter Proxy verweigert	`use_x_forwarded_for: true` und `trusted_proxies` in der `configuration.yaml` ergänzen (Netzadresse, keine Host-IP).
Container startet nicht / Fehler unklar	Logs prüfen mit `docker logs -f homeassistant` und Konfiguration mit `check_config` validieren.

Häufige Fragen

Was ist der Unterschied zwischen Home Assistant Container und HAOS?

Home Assistant OS (HAOS) bringt den Supervisor mit und damit Ein-Klick-Add-ons, integrierte Backups und automatische Updates. Die Container-Variante ist schlanker und läuft als reiner Docker-Container - dafür organisierst du Add-on-Ersatz, Updates und Backups selbst. Für Admins mit vorhandenem Docker-Host ist der Container oft die flexiblere Wahl.

Brauche ich eine GPU für Home Assistant?

Nein. Home Assistant selbst kommt ohne GPU aus. Erst rechenintensive Zusatzdienste in eigenen Containern (lokales LLM-Serving, Bildgenerierung/-erkennung) profitieren von einer GPU plus nvidia-container-toolkit - das ist aber kein Bestandteil von Home Assistant.

Wie aktualisiere ich Home Assistant im Container?

Mit docker compose pull homeassistant ziehst du das neue Image und mit docker compose up -d ersetzt du den Container. Prüfe vorher die Release Notes und lege ein Backup des config-Verzeichnisses an, da der Tag stable größere Versionssprünge enthalten kann.

Kann ich Mosquitto, Zigbee2MQTT oder ESPHome trotzdem nutzen?

Ja - nur eben nicht als Add-on. Du betreibst sie als separate Docker-Container und verbindest sie über das Netzwerk mit Home Assistant (z. B. MQTT-Broker als eigener Container, in Home Assistant die MQTT-Integration konfigurieren).

Warum funktioniert die Geräteerkennung nicht?

Fast immer fehlt network_mode: host. Auto-Discovery über mDNS, SSDP und UPnP braucht direkten Zugriff auf das Host-Netz. Ohne Host-Netz musst du Port 8123 mappen und Integrationen manuell hinzufügen.

Wie sichere ich meine Installation?

Sichere das komplette config-Verzeichnis - es enthält Konfiguration, Datenbank, Automatisierungen und Geheimnisse. Stoppe den Container für ein konsistentes Backup, packe das Verzeichnis in ein Archiv und lege es außerhalb des Servers ab.

Fazit

Mit Home Assistant Container betreibst du eine vollwertige, lokale Smart-Home-Zentrale ohne Cloud-Abhängigkeit - sauber als Docker-Stack, den du jederzeit verstehst und kontrollierst. Die compose.yaml ist schnell erstellt, das Onboarding führt dich durch die Ersteinrichtung, und Geräte bindest du dank Auto-Discovery oft mit wenigen Klicks an. Den Preis für die Flexibilität zahlst du an zwei Stellen: Add-ons ersetzt du durch eigene Container, und Updates wie Backups organisierst du selbst. Beides ist mit den gezeigten Befehlen Routine. Wer einen Docker-Host betreibt, hat damit in unter einer Stunde eine robuste, datensparsame Smart-Home-Basis stehen.

Weiterführende Anleitungen und Quellen

Quellen: