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.

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

Step 2: Install Node

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

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

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