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 the Homebridge 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

• 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 requires Node.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 working
node -v

# Test npm is working
npm -v

Install Homebridge and the Homebridge 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 provided hb-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 Homebridge config.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 to http://localhost:8581.

The Homebridge 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 the Configuration 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 supports Child Bridges which are an easier-to-manage alternative to running multiple instances.

Some users prefer to run multiple instances of Homebridge.

The hb-service command makes this easy via the --service-name flag.

See the hb-service documentation for instructions.

It is recommended to run Homebridge on the current 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 in System 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 (replace My-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 (replace MY_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 select Settings

10. Select UI Advanced Settings

11. Expand the SSL Settings accordion

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

13. In the PKCS#12 Certificate Passphrase field, enter the passphrase you used in place of MY_SECRET above

14. Click Save

15. Do not restart the server when asked

16. On the Settings page, click the button next to JSON 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 the Save button (floppy disk icon)

19. Restart the Homebridge UI

20. Access your Homebridge server at https://YOUR_SERVERS_IP_ADDRESS

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