Install Homebridge on macOS
This guide provides step-by-step instructions to show you how to install Homebridge on macOS as a service so it will automatically start on boot.
- Prerequisites
- Installing Homebridge
- How To Uninstall Homebridge
- Multiple Instances
- Major Node.js Version Updates
- Configuration Reference
- MacOS 15.0 Sequoia
Before you get started, make sure you have the following ready:
- A computer running a recent version of macOS that is always powered on.
- Access to the terminal. You can find the Terminal app using launch pad. You will need the ability to copy and paste commands from this guide into the terminal.
- This guide is intended to be used on machines that do not yet have Homebridge installed. Please make sure you remove any existing installations of Homebridge before you get started.
- Apple Silicon / M1 devices are supported natively.
Homebridge requires Node.js installed on your system to run. Download the LTS version of Node.js (v20.9.0) and run the installer with all the default options selected:
From a Terminal window test that Node.js is working:
# test node.js is working
node -v
# test npm is working
npm -vInstall Homebridge and the Homebridge UI using the following command:
sudo npm install -g --unsafe-perm homebridge homebridge-config-ui-x
To set up Homebridge as a service that will start on boot you can use the provided hb-service command.
sudo hb-service install
This command will do everything that is required to set up Homebridge and the Homebridge UI as a service.
The Homebridge service will be set up using the user account you are currently logged in as and does not require sudo/root privileges once set up.
The Homebridge config.json can be found under ~/.homebridge and will be created automatically if it does not already exist.
Login to the web interface by going to http://localhost:8581.
The Homebridge UI web interface will allow you to install, remove and update plugins, and modify the Homebridge config.json and manage other aspects of your Homebridge service.
Review the Configuration Reference at the bottom of this guide.
To remove the Homebridge service run:
sudo hb-service uninstall
To remove Homebridge and Homebridge Config UI X run:
sudo npm uninstall --location=global homebridge homebridge-config-ui-x
💡 Homebridge now supports Child Bridges which are an easier-to-manage alternative to running multiple instances.
Some users like to run multiple instances of Homebridge.
The hb-service command makes this easy to do via the --service-name flag.
See the hb-service documentation for instructions.
It is recommended to run Homebridge on the current stable LTS version of Node.js. You can update Node.js to the current LTS version of Node.js by running:
sudo hb-service update-node This table contains important information about your setup. You can use the information provided here as a reference when configuring or troubleshooting your environment after setting up Homebridge using the instructions below.
| File Location / Command | |
|---|---|
| Config File Path | ~/.homebridge/config.json |
| Storage Path | ~/.homebridge |
| Restart Command | sudo hb-service restart |
| Stop Command | sudo hb-service stop |
| Start Command | sudo hb-service start |
| View Logs Command | hb-service logs |
| Launchctl Service File | /Library/LaunchDaemons/com.homebridge.server.plist |
Click here for the configuration reference for setups done before January 2020
| File Location / Command | |
|---|---|
| Config File Path | ~/.homebridge/config.json |
| Storage Path | ~/.homebridge |
| Restart Command | Run the stop and start commands |
| Stop Command | launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist |
| Start Command | launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist |
| View Logs Command | tail -f ~/.homebridge/homebridge.log |
| Launchctl Service File | ~/Library/LaunchAgents/com.homebridge.server.plist |
MacOS Sequoia introduce new function to control what applications have access to the network. If you have problems with connections, make sure 'node' has access to local network in macOS Settings > Privacy & Security > Local network (if there is no switch for 'node' try reinstalling node).
Homebridge logs could contains messages like this Error: connect EHOSTUNREACH 192.168.0.72:80
- Do NOT generate the certificate with Keychain Access. It will export export certificate/key combinations in .p12 format with the RC2-40-CBC Algorithm which is NOT supported by OpenSSL 3.x.
- Install Homebrew if that hasn't already been done.
- Use homebrew to install openssl which will be 3.4.0 at the moment...
brew install openssl - Generate the key and certificate signing request (replace My-Server-Name with whatever you call your server substituting hyphens for spaces)...
openssl req -new -newkey rsa:2048 -nodes -keyout homebridge.key -out homebridge.csr -subj "/CN=My-Server-Name.local" - Generate a certificate with whatever validity period you want
openssl x509 -req -days 365 -in homebridge.csr -signkey homebridge.key -out homebridge.crt - Convert the certificate and private key to a p12 file (replace MY_SECRET with a secure passphrase of your own)
openssl pkcs12 -export -out homebridge.p12 -inkey homebridge.key -in homebridge.crt -name "Homebridge Certificate" -passout pass:MY_SECRET - Use chown to change the owner and group of your p12 file to match whichever account Homebridge runs under like
chown myusername:staff homebridge.p12 - Use chmod to change the permissions of your p12 file
chmod 600 homebridge.p12 - In the Homebridge UI, go to the three vertical dots on the upper right -> Settings
- Select UI Advanced Settings.
- Expand SSL Settings accordion.
- In the Path To PKCS#12 Certificate field, enter the full path to the newly created p12 file.
- In the PKCS#12 Certificate Passphrase field, enter the passphrase you entered in place of MY_SECRET above.
- Click Save.
- Do not restart the server when asked.
- On the Settings page, click the button next to JSON Config.
- In the JSON for "platforms", there is an object in the array called "Config". Change its "port" value to 443 as long as this does not conflict with anything else running on your Mac.
- Click the Save button (floppy disk icon for some unknown reason).
- Restart the Homebridge UI.
- Access your Homebridge server at https://YOUR_SERVERS_IP_ADDRESS