Homemanager Docs
macOS
Set up Homebridge on macOS step by step: Native setup with hb-service, sleep prevention, macOS 15 Sequoia permissions, and troubleshooting.
How to install Homebridge on macOS
A stationary Mac, especially a Mac mini with Apple Silicon (M1, M2, or M4), makes a practical home server for Homebridge. In continuous operation, modern Apple Silicon models typically draw between 7 and 15 watts. They produce little fan noise and provide enough processing power to handle video transcoding for security cameras using plugins like FFmpeg or Scrypted without dropping frames.
Homebridge runs as a background service on macOS. The Mac needs to stay awake and connected to your network so accessories stay reachable. The steps below cover installing the background daemon, adjusting macOS sleep settings, and connecting from the Homemanager app on iPhone and iPad or through a browser.
Hardware choices: which Mac works best?
Stationary Macs handle continuous server workloads much better than laptops. A dedicated bridge belongs in a fixed spot, ideally wired directly to your router with an Ethernet cable, without being interrupted by closed lids or energy-saving sleep states.
| Model | Recommendation | Practical Notes |
|---|---|---|
| Mac mini (Apple Silicon: M1, M2, M4) | Recommended | Low power consumption (roughly 7 to 15 watts in active operation), quiet, Gigabit Ethernet, and hardware-accelerated video decoding. |
| Mac mini (Intel, 2012 to 2018) | Suitable | Inexpensive on the used market. Power consumption is higher at 15 to 35 watts, and cooling fans become audible under plugin workloads. |
| iMac / Mac Studio | Suitable | Plenty of processing power, but an iMac is impractical as a dedicated headless server because its built-in display draws unnecessary power when active. |
| MacBook (Air / Pro) | Conditionally suitable | Useful only for testing. Running plugged in continuously accelerates battery wear, and closing the lid triggers sleep mode unless external hardware is attached. |
Installation methods overview
Two main setup paths are available on macOS:
- Native installation with hb-service (recommended): Homebridge and Node.js run directly on macOS. A LaunchDaemon starts the service on boot before user login. This keeps resource usage minimal and grants plugins direct access to the local network and hardware.
- Virtual machine with UTM: An isolated Linux VM using the official Homebridge VM image. Useful if you prefer not to install global Node.js packages directly on the host system.
Note on Docker Desktop for Mac:
Docker Desktop on macOS runs containers inside a Linux virtual machine. Because of that network layer, the container cannot bridge mDNS and Bonjour packets to your local network. Apple Home frequently fails to discover or communicate with accessories as a result. Running Homebridge natively on macOS avoids this problem.
Native installation (step by step)
You install Homebridge through Terminal and register it as a system service with hb-service. The service then runs in the background without requiring an active user login.
Install Xcode command line tools
Several Homebridge plugins, like Bluetooth integrations or media tools, compile native C/C++ code during installation. macOS requires Apple command-line developer tools for this step.
Open Terminal (via Spotlight or under Applications > Utilities) and run:
xcode-select --installClick Install when the system dialog appears and wait for the download to finish. If the tools are already installed, Terminal prints a brief message.
Install Node.js LTS
Homebridge runs on Node.js and requires an active LTS release (we recommend Node.js LTS v24.x or v22.x).
For background services on macOS, the official package installer is the most predictable route:
- Download the official macOS installer package (
.pkg) for the current LTS version from nodejs.org. - Open the downloaded file and complete the standard installation steps.
- The package installs Node.js globally into
/usr/local/bin, where system daemons can access it directly.
(Optional via Homebrew): If you already manage tools with Homebrew, you can install Node.js via Terminal:
brew install nodeCheck the installed versions:
node -v
npm -vInstall Homebridge and web interface
Install Homebridge and its web interface globally using npm:
sudo npm install -g --unsafe-perm homebridge homebridge-config-ui-xEnter your Mac administrator password when prompted. The --unsafe-perm flag ensures that internal setup scripts execute with the required system permissions.
Set up background service with hb-service
To make sure Homebridge boots automatically whenever the Mac restarts, configure it as a background service using hb-service:
sudo hb-service installThis creates a LaunchDaemon at /Library/LaunchDaemons/com.homebridge.server.plist. The service starts during system boot before any user logs in. All configuration files, installed plugins, and accessory storage are located in ~/.homebridge inside your user folder.
Important macOS settings for 24/7 server operation
Because macOS is designed as a desktop operating system, it aggressively puts idle hardware to sleep. To keep Homebridge accessible around the clock, adjust a few system settings:
1. Prevent sleep when the display turns off
When macOS enters sleep, network connections drop and Apple Home immediately marks all bridged accessories as "No Response".
Configure these settings in System Settings:
- In Lock Screen (or Displays), turn on Prevent automatic sleeping when the display is off.
- In Energy Saver, turn on Start up automatically after a power failure.
- In Network, open your active connection's advanced settings and enable Wake for network access (Wake on LAN).
For headless servers without an attached monitor, turning off sleep in Terminal is the most reliable approach:
sudo pmset -a sleep 0 displaysleep 10 disksleep 0This command disables system sleep (sleep 0) and disk spindown (disksleep 0), while still allowing any attached display to turn off after 10 minutes of inactivity.
Running on a MacBook:
Closing a MacBook lid forces macOS into sleep mode by default. Running with the lid closed (clamshell mode) requires the laptop to stay connected to power, with at least one external monitor or an inexpensive HDMI dummy plug attached.
2. macOS 15 (Sequoia): Local network permissions
Starting with macOS 15 Sequoia, Apple requires explicit user permission for processes communicating on the local network. If node lacks this permission, Homebridge cannot discover local accessories or publish mDNS records (Error: connect EHOSTUNREACH).
To check permissions:
- Open System Settings > Privacy & Security.
- Select Local Network.
- Confirm that the toggle switch next to node is turned on.
3. Check macOS application firewall
If the built-in macOS firewall is enabled (System Settings > Network > Firewall), it can block incoming connections:
- Click Options in the Firewall settings panel.
- Check that Automatically allow built-in software to receive incoming connections is enabled.
- Verify that node is listed and set to Allow incoming connections. Otherwise, port 8581 and Apple Home pairing ports will reject connections from other devices.
4. Headless boots and FileVault
If FileVault disk encryption is enabled on your Mac, the machine halts at the pre-boot login screen after every reboot. The startup volume remains encrypted until someone enters a user password on a physical keyboard, preventing any background LaunchDaemons from starting.
If your Mac operates without a screen in a closet or network cabinet:
- Enable macOS Screen Sharing (VNC) so you can unlock the drive remotely from another computer after an unexpected reboot.
- On a dedicated home automation server that stores no personal files, you can turn off FileVault so Homebridge restarts cleanly after power outages or software updates.
5. Control automatic system updates
Under System Settings > General > Software Update, macOS tends to install updates overnight and restart the computer. To prevent unplanned bridge outages, turn off automatic updates and install macOS updates manually when you have time to supervise the reboot.
Connecting and Initial Setup
Once the background service is running, Homebridge is available on your local network. The web interface (homebridge-config-ui-x) acts as the browser dashboard and provides the API that Homemanager connects to.
The instance runs unencrypted over port 8581 by default.
Because this is a fresh setup without existing accounts, you create an administrator account during the first connection. You can do this in the app or in a browser:
Setup with Homemanager
Homemanager lets you manage instances on iPhone and iPad, monitor live logs, and configure plugins.
Discover the server
Open Homemanager while connected to the same Wi-Fi network as your Mac. Tap Connect to Server during initial launch (or Add Platform in the platform list). The app scans the local network using mDNS and Bonjour.
Select the instance
Choose the detected server from the list. It shows the Homebridge icon (default name: homebridge or your Mac's hostname) and port 8581.
Create an administrator account
Homemanager detects the new server and opens the Create new User screen. Enter a display name, username (such as admin), and password, then tap Create and Log In.
The account is created directly on the server, credentials are saved securely in your iOS Keychain, and Homemanager connects immediately.
Discovery issues or blocked by the macOS firewall? Refer to Connecting Servers to Homemanager for manual IP and port configuration and network troubleshooting.
Setup in the Web Browser
To configure the server from your Mac or a computer on the network, open the interface in a desktop browser.
Open the URL
Navigate to the web interface in your browser:
- On the Mac:
http://localhost:8581 - From another computer on the network:
http://<mac-ip-address>:8581(orhttp://homebridge.local:8581)
Create an account or restore a backup
Enter a username and password for the admin account. If migrating from an earlier setup, you can restore a backup archive here instead.
After signing in, the dashboard displays the HomeKit pairing code.
Useful terminal commands
The hb-service command-line utility lets you control and maintain the background service directly from the macOS Terminal:
# Restart the Homebridge service
sudo hb-service restart
# Stop the service
sudo hb-service stop
# Start the service
sudo hb-service start
# Check current service status
sudo hb-service status
# View live service logs
sudo hb-service view-logs
# Reset administrator password (resets login to admin/admin)
sudo hb-service reset-admin
# Update Node.js to the recommended LTS release
sudo hb-service update-node
# Recompile native npm modules after a Node or macOS update
sudo hb-service rebuild
# Completely remove the background service
sudo hb-service uninstallFor ongoing maintenance advice regarding Node.js, npm, and plugins, check our guide on Updating System Software.
Alternative: Virtual machine with UTM
If you prefer to keep your macOS installation completely free of Node.js packages and build tools, you can run Homebridge inside an isolated virtual machine.
The official Homebridge VM Image includes a lightweight, preconfigured Linux system. It runs in the free, open-source virtualization application UTM, which is optimized for both Apple Silicon (ARM64) and Intel chips.
Unlike Docker Desktop, UTM supports full bridged networking with native mDNS and multicast pass-through, allowing Apple Home and the Homemanager app to discover and control devices without routing issues.
Frequently asked questions and troubleshooting
Next steps
Once Homebridge is up and running on your Mac:
-
Pair with Apple Home:
Find the setup QR code in the Homemanager app or web dashboard. Open Apple Home on your iPhone, tap the plus icon, choose Add Accessory, and scan the code.
Guide to Pairing with Apple Home -
Install plugins:
Browse Homemanager or the web interface for plugins matching your accessories (such as Ring, Tuya, FritzBox, cameras, or Shelly).
Tips on Finding and Evaluating Plugins -
Set up child bridges:
Isolate resource-heavy plugins (like video cameras) into independent processes so an issue in one plugin cannot interrupt the rest of your home.
Learn More About Child Bridges
Further reading
Guides in Homemanager Docs
- Hardware Comparison: Choosing the Best System for Homebridge
- Connecting Servers to Homemanager
- Updating System Software & Node.js Safely
- Startup Errors & Log Analysis
- Troubleshooting Startup Errors
Official Homebridge Resources
Docker & Containers
Set up Homebridge with Docker or Docker Compose on Linux, Synology NAS, or Unraid. Covers host networking, permissions, and troubleshooting.
Windows
Set up Homebridge on Windows 10 and 11 as a background service. Step-by-step setup, firewall rules, sleep settings, and connecting via mobile app.