Homebridge Service Command

Homebridge Config UI X provides the hb-service command which makes it easy to setup 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

Features

In addition to the features Homebridge Config UI X provides to all users, those who setup 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
✔️   Automated creation of default config.json and storage folders
✔️   Syntax validation and repair of the Homebridge config.json on start
✔️   The ability to clear the 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 Node.js 10 or higher.

The hb-service command is intended for new Homebridge installations. If you already have Homebridge setup 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 service on Linux
• Setup Homebridge as service on Windows 10
• Setup Homebridge as service on macOS

Setup a Homebridge Service

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

Linux:

On Linux you need to use sudo and pass the --user attribute to specify which use the service should be installed as. 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 setup using the user account you are currently logged in as and does not require sudo/root privileges once setup.

sudo hb-service install

Windows 10:

On Windows 10 this command needs to be run an 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

If you need to run more than one instance of Homebridge for whatever reason, you can use the --service-name flag to pass 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:

hb-service install --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