Homebridge auf macOS installieren

Ein stationärer Mac, vor allem ein Mac mini mit Apple Silicon (M1, M2 oder M4), ist eine praktische Basis für Homebridge. Im Dauerbetrieb liegt der Verbrauch moderner Modelle meist bei 7 bis 15 Watt. Die Rechner laufen leise und bringen genug Rechenleistung mit, um auch Kamera-Streams über Plugins wie FFmpeg oder Scrypted ohne Aussetzer umzurechnen.

Damit Homebridge deine Geräte zuverlässig schaltet, muss der Mac durchlaufen und darf nicht in den Ruhezustand wechseln. Diese Anleitung zeigt die Einrichtung als Hintergrunddienst und die anschließende Verbindung mit der Homemanager App auf iPhone und iPad oder über den Browser.

Hardware-Wahl: Welcher Mac eignet sich?

Für ein stabiles Setup eignen sich stationäre Macs deutlich besser als Laptops. Ein Server sollte an einem festen Ort stehen, am besten per Ethernet-Kabel am Router hängen und nicht durch zugeklappte Displays oder Energiesparpläne gestoppt werden.

Installationswege im Überblick

Für macOS gibt es zwei Wege:

1. Native Installation mit hb-service (empfohlen): Homebridge und Node.js laufen direkt unter macOS. Ein LaunchDaemon startet Homebridge beim Booten automatisch im Hintergrund. Das spart Ressourcen und gibt Plugins direkten Zugriff auf Netzwerk und Hardware.
2. Virtuelle Maschine mit UTM: Eine getrennte Linux-VM mit dem offiziellen Homebridge VM Image. Sinnvoll, wenn das macOS-System frei von Node.js-Paketen bleiben soll.

Native Installation (Schritt für Schritt)

Die native Einrichtung erfolgt im macOS-Terminal. Homebridge wird dabei als systemweiter Dienst eingerichtet, der auch ohne angemeldeten Benutzer läuft.

xcode-select --install

brew install node

node -v
npm -v

sudo npm install -g --unsafe-perm homebridge homebridge-config-ui-x

sudo hb-service install

Wichtige macOS-Einstellungen für den 24/7-Dauerbetrieb

Da macOS für den Schreibtischbetrieb gedacht ist, legt das Betriebssystem ungenutzte Rechner nach einiger Zeit schlafen. Damit Homebridge rund um die Uhr erreichbar bleibt, sind ein paar Anpassungen nötig:

1. Ruhezustand bei ausgeschaltetem Bildschirm verhindern

Sobald macOS in den Ruhezustand wechselt, bricht die Netzwerkverbindung ab. In Apple Home erscheint bei allen Zubehören der Status „Keine Antwort“.

Passe folgende Optionen in den Systemeinstellungen an:

• Sperrbildschirm / Displays: Schalte die Option Automatisches Aktivieren des Ruhezustands bei ausgeschaltetem Display verhindern ein.
• Energie sparen: Aktiviere Nach Stromausfall automatisch neu starten.
• Netzwerk: Aktiviere in den erweiterten Einstellungen deiner Netzwerkverbindung Ruhezustand bei Netzwerkzugriff beenden (Wake on LAN).

Für Rechner ohne Monitor lässt sich der Ruhezustand am einfachsten über das Terminal dauerhaft abschalten:

sudo pmset -a sleep 0 displaysleep 10 disksleep 0

Dieser Befehl schaltet den System-Ruhezustand (sleep 0) und das Schlafen der Festplatten (disksleep 0) ab. Der Monitor schaltet sich nach 10 Minuten Inaktivität weiterhin aus.

2. macOS 15 (Sequoia): Berechtigung für das lokale Netzwerk

Unter macOS 15 Sequoia verlangt das Betriebssystem eine Freigabe für Programme, die im lokalen Netzwerk kommunizieren. Fehlt diese Freigabe für Node.js, kann Homebridge Zubehöre im Heimnetz nicht erreichen oder wird per mDNS nicht gefunden (Error: connect EHOSTUNREACH).

So prüfst du die Freigabe:

1. Öffne die Systemeinstellungen > Datenschutz & Sicherheit.
2. Wähle den Menüpunkt Lokales Netzwerk.
3. Vergewissere dich, dass der Schalter neben node aktiviert ist.

3. macOS-Firewall prüfen

Wenn die systemeigene Firewall eingeschaltet ist (Systemeinstellungen > Netzwerk > Firewall), kann sie eingehende Verbindungen blockieren:

1. Klicke in den Firewall-Einstellungen auf Optionen.
2. Prüfe, ob die Option Eingehende Verbindungen automatisch für integrierte Software erlauben aktiv ist.
3. Stelle sicher, dass node in der Liste steht und auf Eingehende Verbindungen erlauben gesetzt ist. Andernfalls sind Port 8581 und die HomeKit-Ports von außen nicht erreichbar.

4. Headless-Betrieb und FileVault

Ist FileVault auf dem Mac aktiv, wartet das System nach einem Neustart am Anmeldebildschirm. Erst wenn jemand das Passwort eingibt, wird die Festplatte entsperrt. Vorher starten keine Hintergrunddienste.

Wenn der Mac ohne Monitor und Tastatur betrieben wird:

• Richte die macOS-Bildschirmfreigabe (VNC) ein, um das Passwort nach einem Neustart von einem anderen Rechner im Heimnetz einzugeben.
• Auf einem reinen Smart-Home-Rechner ohne persönliche Dateien kannst du FileVault auch abschalten. Dann startet Homebridge nach Stromausfällen oder Updates ohne Eingabe durch.

5. Automatische System-Updates steuern

Unter Systemeinstellungen > Allgemein > Softwareupdate installiert macOS Aktualisierungen oft nachts und startet den Rechner neu. Wenn du ungeplante Ausfälle vermeiden willst, deaktiviere automatische macOS-Updates und spiele Aktualisierungen gezielt von Hand ein.

Verbindung herstellen und einrichten

Sobald der Hintergrunddienst läuft, ist Homebridge im Heimnetzwerk erreichbar. Die Weboberfläche (homebridge-config-ui-x) dient als Browser-Dashboard und stellt die API bereit, über die sich auch Homemanager verbindet.

Die Instanz läuft standardmäßig unverschlüsselt über Port 8581.

Da noch kein Benutzer existiert, legst du beim ersten Verbinden ein Administratorkonto an. Das geht in der App oder im Browser:

Nützliche Befehle im Terminal

Über das Befehlswerkzeug hb-service lässt sich der Hintergrunddienst jederzeit über das macOS-Terminal verwalten und warten:

# Homebridge-Dienst neu starten
sudo hb-service restart

# Homebridge-Dienst stoppen
sudo hb-service stop

# Homebridge-Dienst starten
sudo hb-service start

# Aktuellen Status des Dienstes abfragen
sudo hb-service status

# Live-Logs direkt im Terminal verfolgen
sudo hb-service view-logs

# Administrator-Passwort zurücksetzen (setzt Dashboard & App-Login auf admin/admin)
sudo hb-service reset-admin

# Node.js sicher auf die empfohlene LTS-Version aktualisieren
sudo hb-service update-node

# Native npm-Module nach einem Node- oder macOS-Update neu kompilieren
sudo hb-service rebuild

# Hintergrunddienst sauber deinstallieren
sudo hb-service uninstall

Alternative: Virtuelle Maschine mit UTM

Wer auf dem Host-Betriebssystem keine globalen Node.js-Pakete oder Compiler-Werkzeuge installieren möchte, kann Homebridge in einer virtuellen Maschine isolieren.

Das offizielle Homebridge VM Image bringt ein schlankes, vorkonfiguriertes Linux-System mit. Es läuft in der kostenlosen Open-Source-App UTM, die sowohl für Apple Silicon (ARM64) als auch für Intel-Prozessoren optimiert ist.

Im Gegensatz zu Docker Desktop unterstützt UTM über eine virtuelle Netzwerkbrücke (Bridged Network) echtes mDNS und Multicast, sodass Apple Home und die Homemanager App die Instanz im Heimnetzwerk ohne Verbindungsprobleme erkennen.

Häufige Fragen und Fehlerbehebung

Nächste Schritte

Sobald deine Homebridge-Instanz auf dem Mac eingerichtet ist und stabil läuft:

1. Mit Apple Home koppeln:
   Sowohl in der Weboberfläche als auch in Homemanager findest du den Einrichtungs-QR-Code. Öffne auf deinem iPhone die Apple-Home-App, tippe auf das Plus-Symbol, wähle Gerät hinzufügen und scanne den Code.
   Anleitung zur Kopplung mit Apple Home

2. Plugins installieren:
   Suche über Homemanager oder das Web-Dashboard nach Erweiterungen für deine Geräte (z. B. FritzBox, Tuya, Kameras oder Shelly).
   Tipps zur Auswahl und Bewertung von Plugins

3. Child Bridges einrichten:
   Lagere Plugins für Kameras oder komplexe Bridges in separate Teilprozesse aus, um das Hauptsystem zu isolieren.
   Mehr über Child Bridges erfahren

Weiterführende Links

Anleitungen in den Homemanager Docs

• Hardware-Vergleich: Das beste System für Homebridge
• Server mit Homemanager verbinden
• System-Software & Node.js sicher aktualisieren
• Startprobleme & Logs analysieren
• Startprobleme von Homebridge beheben

Offizielle Homebridge-Ressourcen

• Offizielles Homebridge Wiki: Install Homebridge on macOS
• Homebridge Service Command (hb-service) Wiki
• Homebridge Troubleshooting Leitfaden