This guide provides instructions for installing Homebridge on macOS as a service that will automatically start on boot.

There are two ways to run Homebridge on macOS:

We recommend using theHomebridge VM Image for a streamlined experience. This provides:

• Pre-configured environment with Homebridge, Node.js, and all dependencies
• Automatic updates and easier maintenance
• Better isolation from your main system
• Works on both Intel and Apple Silicon Macs
• Simpler backup and restore process

View Homebridge VM Image Installation Instructions →

The VM Image supports UTM (recommended for macOS) and VirtualBox.

The instructions below describe installing Homebridge directly on your macOS system. This method is ideal for:

• Users who want Homebridge running directly on their Mac
• Users who prefer not to use virtualization
• Advanced users who need direct system access
• Users with specific hardware requirements or plugins that need native access
• Users of camera plugins likehomebridge-unifi-protect

• Homebridge on macOS
  • Installation Options
    • Option 1: Virtual Machine (Recommended for Most Users)
    • Option 2: Native Installation
  • Native Installation Instructions
    • Table of Contents
    • Prerequisites
    • Installing Homebridge
      • Step 1: Install Node.js
        • Download Node.js v22.18.0 macOS Installer
      • Step 2: Install Homebridge and Homebridge UI
      • Complete: Login to the Homebridge UI
    • How To Uninstall Homebridge
    • Multiple Instances
    • Major Node.js Version Updates
    • Configuration Reference
    • macOS 15.0 Sequoia
      • To setup Homebridge on macOS Sequoia to use a self-signed SSL certificate...
  • Need Help?

Before you get started, make sure you have the following:

• A computer running a recent version of macOS that is always powered on
• Access to the Terminal app (found in Applications > Utilities or via Spotlight search)
• The ability to copy and paste commands from this guide into Terminal
• This guide is intended for machines that do not yet have Homebridge installed. Please remove any existing installations of Homebridge before you get started
• Apple Silicon / M1/M2/M3 devices are fully supported

Homebridge requiresNode.js installed on your system to run. Download the LTS version of Node.js (v22.18.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 workingnode -v# Test npm is workingnpm -v

InstallHomebridge and theHomebridge 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, use the providedhb-service command:

sudo hb-service install

This command will configure everything 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 Homebridgeconfig.json can be found under~/.homebridge and will be created automatically if it does not already exist.

Log in to the web interface by navigating tohttp://localhost:8581.

TheHomebridge UI web interface allows you to install, remove and update plugins, modify the Homebridge config.json, and manage other aspects of your Homebridge service.

Review theConfiguration Reference section below for important information about managing your installation.

To remove the Homebridge service, run:

sudo hb-service uninstall

To remove Homebridge and the Homebridge UI, run:

sudo npm uninstall --location=global homebridge homebridge-config-ui-x

💡 Homebridge now supportsChild Bridges which are an easier-to-manage alternative to running multiple instances.

Some users prefer to run multiple instances of Homebridge.

Thehb-service command makes this easy via the--service-name flag.

See thehb-service documentation for instructions.

It is recommended to run Homebridge on thecurrent stable LTS version of Node.js. You can update Node.js to the current LTS version by running:

sudo hb-service update-node

This table contains important information about your setup. Use this as a reference when configuring or troubleshooting your environment.

macOS Sequoia introduced new functionality to control which applications have access to the network. If you experience connection problems, ensure that 'node' has access to the local network inSystem Settings > Privacy & Security > Local network. If there is no switch for 'node', try reinstalling Node.js.

Homebridge logs may contain messages like:Error: connect EHOSTUNREACH 192.168.0.72:80

1. Do NOT generate the certificate with Keychain Access. It will export certificate/key combinations in .p12 format with the RC2-40-CBC Algorithm which is NOT supported by OpenSSL 3.x

2. Install Homebrew if you haven't already:

   /bin/bash -c"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Use Homebrew to install OpenSSL (currently version 3.4.0):

   brew install openssl

4. Generate the key and certificate signing request (replaceMy-Server-Name with your server name, using hyphens instead of spaces):

   openssl req -new -newkey rsa:2048 -nodes -keyout homebridge.key -out homebridge.csr -subj"/CN=My-Server-Name.local"

5. Generate a certificate with your desired validity period:

   openssl x509 -req -days 365 -in homebridge.csr -signkey homebridge.key -out homebridge.crt

6. Convert the certificate and private key to a p12 file (replaceMY_SECRET with a secure passphrase):

   openssl pkcs12 -export -out homebridge.p12 -inkey homebridge.key -in homebridge.crt -name"Homebridge Certificate" -passout pass:MY_SECRET

7. Change the owner and group of your p12 file to match the account Homebridge runs under:

   chown myusername:staff homebridge.p12

8. Change the permissions of your p12 file:

   chmod 600 homebridge.p12

9. In the Homebridge UI, click the three vertical dots on the upper right and selectSettings

10. SelectUI Advanced Settings

11. Expand theSSL Settings accordion

12. In thePath To PKCS#12 Certificate field, enter the full path to the newly created p12 file

13. In thePKCS#12 Certificate Passphrase field, enter the passphrase you used in place ofMY_SECRET above

14. ClickSave

15. Do not restart the server when asked

16. On the Settings page, click the button next toJSON Config

17. In the JSON under "platforms", find the 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)

18. Click theSave button (floppy disk icon)

19. Restart the Homebridge UI

20. Access your Homebridge server athttps://YOUR_SERVERS_IP_ADDRESS

• For VM Image installation, see theHomebridge VM Image Wiki
• For general Homebridge help, visit theHomebridge Wiki
• Join theHomebridge Discord community