Homebridge Service Command

Homebridge Config UI X provides the hb-service command which makes it easy to set up Homebridge as a service on Linux, macOS and Windows 10.

• Features
• Requirements
• Setup a Homebridge Service
  • Linux
  • macOS
  • Windows 10
• Stopping the Service
• Starting the Service
• Restarting the Service
• View Logs
• Uninstalling
• Multiple Instances
• Homebridge UI Port
• Update Node.js

Features

In addition to the features Homebridge Config UI X provides to all users, those who set up Homebridge using hb-service also get:

✔️   Automatic start on boot
✔️   Automatic restart if Homebridge crashes
✔️   The UI remains online even if Homebridge is crashing due to a config error
✔️   Persistent logs with automatic log rotation
✔️   The ability to download and truncate the log file from the UI
✔️   Automated creation of default config.json and storage folders
✔️   Syntax validation and repair of the Homebridge config.json on start
✔️   The ability to monitor and restart child bridges
✔️   The ability to clear the Homebridge accessory cache from the UI
✔️   The ability to remove selected accessories from Homebridge accessory cache from the UI
✔️   The ability to set the Homebridge -D debug, -R remove orphans, and -I insecure mode flags from the UI
✔️   The ability to set the DEBUG and NODE_OPTIONS environment variables from the UI

Requirements

To use the hb-service command you must have Homebridge and Homebridge Config UI X installed globally and be running a supported version of Node.js.

The hb-service command is intended for new Homebridge installations. If you already have Homebridge set up as a service using an alternative method you should not use these commands.

Full step-by-step setup guides for each platform, including instructions on how to install Node.js can be found here:

• Setup Homebridge as a service on Linux
• Setup Homebridge as a service on Windows 10
• Setup Homebridge as a service on macOS

Setup a Homebridge Service

The command to set up a service is basically the same on each platform.

Linux:

💡 Ubuntu / Debian / Raspberry Pi OS (or similar) users should follow this guide

On Linux you need to use sudo and pass the --user attribute to specify for which user the service should be installed. If the user does not exist it will be created.

sudo hb-service install --user homebridge

macOS:

On macOS you need to use sudo to do the initial installation. 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.

sudo hb-service install

Windows 10:

On Windows 10 this command needs to be run in a Node.js command prompt running as Administrator. See the full guide here.

hb-service install

Stopping the Service

To stop the Homebridge service:

hb-service stop

Starting the Service

To start the Homebridge service:

hb-service start

Restarting the Service

To restart the Homebridge service:

hb-service restart

View Logs

To tail the Homebridge service logs at the command line run:

hb-service logs

Uninstalling

Run the following command to stop Homebridge and remove the service from your system:

hb-service uninstall

Multiple Instances

💡 Homebridge now supports Child Bridges which is an easier way to run multiple instances.

⚠️ Multiple instance support is now depreciated, use Child Bridges instead.

If you need to run more than one instance of Homebridge for whatever reason, you can use the --service-name flag to specify an alternate instance name. Note that Homebridge refers to the default instance.

You will also need to pass in the --port flag to specify which port you want the UI to run on. If a service is already running on that port you won't be able to install the service.

Create a new secondary instance:

# macOS / Windows:
hb-service install --service-name homebridge-two --port 8080

# Linux / Raspbian:
hb-service install --user homebridge --service-name homebridge-two --port 8080

To manage your secondary instances you need to pass the --service-name flag each time, for example:

Tip: You can use the -S flag instead of --service-name.

hb-service stop -S homebridge-two
hb-service start -S homebridge-two
hb-service restart -S homebridge-two
hb-service logs -S homebridge-two
hb-service uninstall -S homebridge-two

Homebridge UI Port

You can set the port the Homebridge UI will use during installation using the --port flag. For example:

hb-service install --port 8080

Update Node.js

This feature is not available on Windows.

The hb-service update-node command helps you update Node.js on Linux and macOS.

This command checks how you previously installed Node.js, and installs the new version the same way. This is to ensure you don't end up with multiple copies installed.

To update to the latest LTS version of Node.js, or to the latest minor version of your current Node.js version (whichever is greater), run:

sudo hb-service update-node

To install a specific version, you can add the version number to the command:

sudo hb-service update-node 20.10.0

This command will only work when Node.js is installed in one of the following locations:

• /usr/bin/node
• /usr/local/bin/node