Homebridge UI 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
Before you get started, make sure you have the following ready:
- A computer running a recent version of macOS.
- 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.
Download Node.js from https://nodejs.org/en/download/ 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 Homebridge Config UI X using the following command:
sudo npm install -g --unsafe-perm homebridge homebridge-config-ui-x
To setup 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 setup Homebridge and the Homebridge UI as a service.
The Homebridge service will be setup using the user account you are currently logged in as and does not require sudo/root privileges once setup.
The default Homebridge config.json under ~/.homebridge will be created it does not already exist.
The Homebridge Config UI X 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.
Login to the web interface by going to http://localhost:8581.
The default user is admin with password admin.
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 -g homebridge homebridge-config-ui-x
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.
You can upgrade Node.js using the same method you used to install it initially in Step 1.
After doing a major update to Node.js you may need to rebuild certain plugins:
cd $(npm -g prefix)/lib/node_modules
npm rebuildThis 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 |