Homebridge UI on macOS

This guide will show you how to setup Homebridge and Homebridge Config UI X using launchctl on macOS.

Step 1: Install Homebrew

Homebrew is a package manager for macOS. You may be prompted to install some xcode utilities, ensure this completes successfully before proceeding to the next step.

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Step 2: Install Node.js

Install Node.js using brew:

brew install node

Step 3: Install Homebridge and Homebridge Config UI X

npm install -g --unsafe-perm homebridge homebridge-config-ui-x

Step 4: Create Default config.json

Ensure the ~/.homebridge directory exists:

mkdir -p ~/.homebridge

Use the following command to create the default config.json file:

Copy and paste this entire block into the terminal as one command!

cat >/Users/$(whoami)/.homebridge/config.json <<EOL
{
    "bridge": {
        "name": "Homebridge on macOS",
        "username": "CB:22:3D:E2:CE:21",
        "port": 51822,
        "pin": "033-43-254"
    },
    "accessories": [],
    "platforms": [
        {
            "name": "Config",
            "port": 8080,
            "auth": "form",
            "theme": "teal",
            "log": {
                "method": "file",
                "path": "/Users/$(whoami)/.homebridge/logfile.log"
            },
            "platform": "config"
        }
    ]
}
EOL

Step 6: Create Launchctl Service

Ensure the ~/Library/LaunchAgents folder exists:

mkdir -p ~/Library/LaunchAgents

Use the command below to create the required ~/Library/LaunchAgents/com.homebridge.server.plist file:

Copy and paste this entire block into the terminal as one command!

cat >/Users/$(whoami)/Library/LaunchAgents/com.homebridge.server.plist <<EOL
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>RunAtLoad</key>
        <true/>
    <key>KeepAlive</key>
        <true/>
    <key>Label</key>
        <string>com.homebridge.server</string>
    <key>ProgramArguments</key>
        <array>
             <string>$(which homebridge)</string>
             <string>-I</string>
        </array>
    <key>StandardOutPath</key>
        <string>/Users/$(whoami)/.homebridge/logfile.log</string>
    <key>StandardErrorPath</key>
        <string>/Users/$(whoami)/.homebridge/logfile.log</string>
    <key>EnvironmentVariables</key>
        <dict>
        <key>PATH</key>
            <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        <key>HOME</key>
            <string>/Users/$(whoami)</string>
        </dict>
</dict>
</plist>
EOL

Step 7: Start Homebridge

This will ensure Homebridge starts on boot:

launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist

To stop Homebridge:

launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist

Step 8: Manage and Configure Homebridge

To manage Homebridge go to http://localhost:8080 in your browser. From here you can install, remove and update plugins, modify the Homebridge config.json and restart Homebridge.

The default username is admin with password admin. Remember you will need to restart Homebridge to apply any changes you make to the config.json.

The Homebridge logs can be viewed using the web interface, but if you need to view them via the terminal run:

tail -f ~/.homebridge/logfile.log

Uninstall Steps

Remove launchctl service:

# stop homebridge
launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist

# remove service
rm -rf ~/Library/LaunchAgents/com.homebridge.server.plist

Uninstall Homebridge and Homebridge Config UI X:

npm uninstall -g homebridge homebridge-config-ui-x

Uninstall Node.js:

brew remove node