Einrichtung

Mit CloudMatic Connect Home Assistant ist Home Assistant weltweit per Browser und Companion-App erreichbar, unter einer persönlichen Adresse und ohne Portfreigabe im Router. Die Verbindung läuft über einen verschlüsselten VPN-Tunnel, den die CloudMatic App direkt in Home Assistant aufbaut.

• Funktioniert auch hinter DS-Lite und im Mobilfunknetz, da der Tunnel von innen aufgebaut wird
• Aus dem Tunnel ist ausschließlich Home Assistant erreichbar, alle anderen Geräte im Heimnetz bleiben abgeschottet
• Wartungszugänge können freigeschaltet werden
• E-Mail- und SMS-Benachrichtigungen aus Automatisierungen (siehe Benachrichtigungen)

Voraussetzungen

• Home Assistant OS oder Home Assistant Supervised (Apps bzw. Add-ons müssen installiert werden können)
• Ausgehende Verbindungen ins Internet dürfen von der Firewall bzw. dem Router nicht blockiert werden

App installieren

1. In Home Assistant Einstellungen > Apps öffnen und auf App installieren klicken. In älteren Versionen heißt der Bereich Einstellungen > Add-ons > Add-on Store.

2. Oben rechts das Menü (⋮) öffnen, Repositories wählen und folgende Adresse hinzufügen:

   https://github.com/EasySmartHome/cloudmatic-homeassistant-addon
   

3. In der Liste die App CloudMatic auswählen und Installieren klicken.

4. Die App starten und In Seitenleiste anzeigen aktivieren.

Account einrichten

Die Einrichtung erfolgt über den Menüpunkt CloudMatic in der Seitenleiste von Home Assistant. Ein Assistent führt durch die vier Schritte Willkommen, Account, Einrichtung und Fertig.

Neuer Account

1. Auf der Willkommensseite Los geht’s klicken.
2. Unter CloudMatic-Account anlegen E-Mail-Adresse, Name und Anschrift eintragen und mit Account erstellen und verbinden bestätigen.
3. Die App holt anschließend die Konfiguration automatisch ab und baut den Tunnel auf. Das kann einige Minuten dauern, die Seite aktualisiert sich selbst.

Die Zugangsdaten (Benutzername und Kennwort für den Kundenbereich) werden per E-Mail verschickt.

Vorhandenes Konfigurationspaket

Liegt bereits ein Konfigurationspaket für Home Assistant vor (vpnkey_homeassistant.tar.gz), zum Beispiel von einer früheren Installation, kann es unter Ich habe bereits eine CloudMatic-Konfiguration hochgeladen werden. Die App verbindet sich danach direkt.

Home Assistant konfigurieren

Damit Home Assistant Anfragen über den CloudMatic-Tunnel annimmt, muss das CloudMatic-Netz als vertrauenswürdiger Proxy eingetragen sein. Ohne diese Einstellung antwortet Home Assistant beim Fernzugriff mit 400 Bad Request.

Ab Home Assistant 2026.8 unter Einstellungen > System > Netzwerk, Abschnitt HTTP-Server:

1. X-Forwarded-For vertrauen (Trust X-Forwarded-For) aktivieren.
2. 10.251.0.0/16 als vertrauenswürdigen Proxy (Trusted proxies) eintragen.
3. Den Server-Port auf 8123 setzen. Neuere Versionen verwenden standardmäßig Port 80, der CloudMatic-Fernzugriff erwartet aber Port 8123.
4. Speichern und Home Assistant neu starten.

Ältere Versionen in der configuration.yaml (danach Home Assistant neu starten):

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.251.0.0/16

Fernzugriff nutzen

Nach erfolgreicher Einrichtung zeigt die App unter Fernzugriff ist eingerichtet die persönliche Adresse, zum Beispiel https://12345.cloudmatic.de:8123/. Über Im Browser öffnen lässt sich der Zugriff direkt testen. Darunter stehen CloudMatic-ID und Benutzername sowie der Verbindungsstatus des Tunnels. Mit Tunnel neu starten und Tunnel trennen kann die Verbindung verwaltet werden.

Companion-App

Damit die Home Assistant Companion-App unterwegs automatisch die CloudMatic-Adresse und zu Hause die lokale Adresse verwendet, müssen in der App unter Einstellungen > Companion-App > Server & Geräte > (eigener Server) folgende Werte eingetragen werden:

Sicherheit

Die App benötigt erweiterte Rechte, die für einen VPN-Client technisch notwendig sind:

• Host-Netzwerk: Der Tunnel muss im Netzwerk des Hosts enden, damit die CloudMatic-Server Home Assistant direkt erreichen.
• NET_ADMIN und /dev/net/tun: Werden benötigt, um die VPN-Schnittstelle anzulegen und die Firewall-Regeln zu setzen.

Zum Schutz setzt die App strenge Firewall-Regeln: Aus dem CloudMatic-Netz (10.251.0.0/16) ist ausschließlich Home Assistant auf Port 8123 erreichbar. Zugriffe auf andere Apps, Dienste oder Geräte im Heimnetz werden verworfen.

Verbindung entfernen

Unter Verbindung entfernen wird der Tunnel getrennt und Profil und Zertifikate werden von diesem Gerät gelöscht. Für eine erneute Nutzung ist eine neue Registrierung oder das erneute Hochladen des Konfigurationspakets nötig. Der CloudMatic-Account selbst bleibt dabei bestehen.