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

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

In addition to the features the Homebridge UI 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, -K keep orphans, and -I insecure mode flags from the UI
✔️   The ability to set the DEBUG and NODE_OPTIONS environment variables from the UI

To use the hb-service command you must have Homebridge and the Homebridge UI installed globally and be running a supported version of Node.js (currently v22.12.0 or later, v24 or v26).

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.

If you used the Raspberry Pi image, the Debian / Ubuntu apt package, the Synology package or Docker, Homebridge is already set up as a service for you. You do not need to run hb-service install, and some commands work differently or are not available.

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

• Setup Homebridge on Debian or Ubuntu Linux
• Setup Homebridge on Red Hat, CentOS or Fedora Linux
• Setup Homebridge on Arch Linux
• Setup Homebridge on Windows
• Setup Homebridge on macOS

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

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

On Linux and FreeBSD 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

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

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

hb-service install

On Linux and macOS, put sudo in front of the commands below. On Windows, run them without sudo from a Node.js command prompt running as Administrator.

These commands are not available inside Docker. Restart the container instead.

To stop the Homebridge service:

sudo hb-service stop

To start the Homebridge service:

sudo hb-service start

To restart the Homebridge service:

sudo hb-service restart

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

sudo hb-service logs

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

sudo hb-service uninstall

This command is not available if you used the Raspberry Pi image, the Debian / Ubuntu apt package or the Synology package.

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

⚠️ Multiple instance support is now deprecated, 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:
sudo hb-service install --service-name homebridge-two --port 8582

# Windows (Administrator command prompt):
hb-service install --service-name homebridge-two --port 8582

# Linux:
sudo hb-service install --user homebridge --service-name homebridge-two --port 8582

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.

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

The Homebridge UI uses port 8581 by default. You can set a different port during installation using the --port flag. For example:

sudo hb-service install --port 8080

On Linux, you also need to add --user, as shown in Setup a Homebridge Service. After installation, you can change the port from the UI in Settings > Homebridge UI Port.

This feature is not available on Windows or FreeBSD.

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

This can move you to a new major version. For example, if you are on v22 and the latest LTS version is v26, it will install v26.

To install a specific version, you can add the version number to the command. For example, to install the latest v24 release:

sudo hb-service update-node 24

Or to install an exact version:

sudo hb-service update-node 22.12.0

The command will not install a version older than v22.12.0. On 32-bit ARM systems (for example 32-bit Raspberry Pi OS), it will not install v24 or later, as Node.js only makes those versions for 64-bit systems. See How To Update Node.js for the supported versions.

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

• Linux: /usr/bin/node or /usr/local/bin/node, or the Node.js that comes with the Homebridge apt package or Synology package
• macOS: /usr/local/bin/node (the official Node.js installer), or the Node.js that comes with the Homebridge macOS package

On Linux, your system also needs a recent enough GLIBC version. See GLIBC requirements.

As above, leave out sudo on Windows.

To check that the Homebridge UI is running (add --port if your UI does not use port 8581):

sudo hb-service status

To rebuild all your plugins and other modules after you change your Node.js version yourself:

sudo hb-service rebuild --all

If you used the Raspberry Pi image, the Debian / Ubuntu apt package or the Synology package, you can install a plugin with hb-service add. See How to Install Alternate Plugin Versions.

To see all the commands, run hb-service with no command.