Repository files navigation

This project builds and publishes a debian-based package that can be installed usingapt on Ubuntu / Debian / Raspberry Pi OS based Linux systems.

The project aims to deploy Homebridge and the Homebridge UI in a secure and stable way, with no dependencies outside those available in the standard distribution repos. It comes bundled with it's own Node.js runtime and runs Homebridge in an isolated environment as a service user with no sudo / admin priviledges.

Supported architectures:

• x86_64 (64-bit Intel/AMD)
• armhf (armv7) - 32-bit ARM (⚠️Node.js version limited to ≤22)
• aarch64 (arm64) - 64-bit ARM

Important: Node.js dropped 32-bit support starting with version 23. The 32-bit ARM (armhf) packages are limited to Node.js 22.x and earlier. Support for 32-bit OS's will end in Spring of 2027.

Add package source:

# make sure the tools needed to add the repo existsudo apt-get updatesudo apt-get install -y curl gpg# add the homebridge gpg keycurl -sSfL https://repo.homebridge.io/KEY.gpg| sudo gpg --dearmor| sudo tee /usr/share/keyrings/homebridge.gpg> /dev/null# add the homebridge repoecho"deb [signed-by=/usr/share/keyrings/homebridge.gpg] https://repo.homebridge.io stable main"| sudo tee /etc/apt/sources.list.d/homebridge.list> /dev/null

Update and install:

sudo apt-get updatesudo apt-get install homebridge

Remove:

sudo apt-get remove homebridge

Purge (this will delete/var/lib/homebridge):

sudo apt-get purge homebridge

Download the correct file for your system fromhttps://github.com/homebridge/homebridge-apt-pkg/releases/latest

dpkg -i homebridge_x.x.x_xxxx.deb

Remove:

dpkg --remove homebridge

Purge (this will delete/var/lib/homebridge):

dpkg --purge homebridge

To update Homebridge, Homebridge UI and NodeJS when installed via this APT package, run:

sudo apt updatesudo apt install homebridge

This will upgrade all related components managed by this package.

⚠️ Your configuration files and plugins are stored in /var/lib/homebridge and will not be affected by updates.

Downgrading will return NodeJS, Homebridge and the Homebridge UI to the version bundled within the apt package. You can view the release manifest of older versions from this page on GitHub -https://github.com/homebridge/homebridge-apt-pkg/releases

If you need to install an older version or previous release of Homebridge:

sudo apt updateapt list -a homebridge# Shows available versionssudo apt install homebridge=<version>

NOTE: apt versions do not start with a v, while the verion on GitHub starts with v

This package contains a self-contained Node.js installation and environment for Homebridge to run in.

The bundled Node.js runtime is isolated and not exposed on the default PATH.

To assist in debugging, a shell commandhb-shell is added to the default PATH to allow the user to enter the Homebridge Shell Environment. When in the Homebridge Shell, users will have access tonode andnpm as they would expect.

# Node.js and package scripts are stored in /opt/homebridge/opt/homebridge# This directory is managed by the homebridge apt package and the contents are overwritten during updates|-- bin||-- node||-- npm||-- npx|-- lib||-- node_modules||-- npm||-- homebridge-config-ui-x|-- bashrc|-- bashrc-hb-shell|-- CHANGELOG.md|-- hb-shell|-- homebridge_apt_pkg_....manifest|-- LICENSE|-- README.md|-- source.sh|-- start.sh# "hb-shell" command to allow user access to the Homebridge env from the cli/usr/local/bin# These links are managed by the homebridge apt package and the contents are overwritten during updates|-- hb-service -> /opt/homebridge/hb-service-shim|-- hb-shell -> /opt/homebridge/hb-shell# homebridge storage directory, plugins are stored in node_modules/var/lib/homebridge|-- node_modules||-- homebridge||-- homebridge-dummy||-- homebridge-hue|-- accessories|-- persist|-- config.json

The Homebridge systemd service will automatically load any environment variables defined in/etc/default/homebridge.

This file can be used to customize the behavior of Homebridge or its plugins at runtime.

After making changes to the file, please useRestart HB Service & UI for your changes to be picked up.

To disable the terminal feature in the Homebridge UI, add the following:

# /etc/default/homebridgeHOMEBRIDGE_CONFIG_UI_TERMINAL=0

You should not edit the service file included with the package as any changes made here will be overwritten during updates.

You should use a systemd override file to make any changes.

To preview the current unit file run:

cat /lib/systemd/system/homebridge.service

Use systemctl to create an override file at/etc/systemd/system/homebridge.service.d/override.conf:

sudo systemctl edit homebridge

Add the config items you want to override.You should only add the settings you want to change.

For example, to change the user the service runs as:

[Service]User=pi# replace with the user you want to run the service as

Or to add additional startup flags to Homebridge:

[Service]ExecStart=ExecStart=/opt/homebridge/start.sh -T

Or to run as root, and allow the UI to shutdown/restart the host:

[Service]User=rootExecStart=ExecStart=/opt/homebridge/start.sh --allow-rootEnvironment="UIX_CAN_SHUTDOWN_RESTART_HOST=1"

Save the file and restart Homebridge:

sudo systemctl restart homebridge

To revert any changes run:

sudo systemctl revert homebridge

Beta builds of the homebridge package are supplied with the latest beta versions of Homebridge and Homebridge UI.

Add package source:

# make sure the tools needed to add the repo existsudo apt-get updatesudo apt-get install -y curl gpg# add the homebridge gpg keycurl -sSfL https://repo.homebridge.io/KEY.gpg| sudo gpg --dearmor| sudo tee /usr/share/keyrings/homebridge.gpg> /dev/null# add the homebridge repoecho"deb [signed-by=/usr/share/keyrings/homebridge.gpg] https://repo.homebridge.io beta main"| sudo tee /etc/apt/sources.list.d/homebridge.list> /dev/null

Update and install:

sudo apt-get updatesudo apt-get install homebridge

Alpha builds of the homebridge package are supplied with the latest alpha versions of Homebridge and Homebridge UI for testing new features before they reach beta.

⚠️Warning: Alpha builds are experimental and may contain bugs or unstable features. Use only for testing purposes.

Add package source:

# make sure the tools needed to add the repo existsudo apt-get updatesudo apt-get install -y curl gpg# add the homebridge gpg keycurl -sSfL https://repo.homebridge.io/KEY.gpg| sudo gpg --dearmor| sudo tee /usr/share/keyrings/homebridge.gpg> /dev/null# add the homebridge repoecho"deb [signed-by=/usr/share/keyrings/homebridge.gpg] https://repo.homebridge.io alpha main"| sudo tee /etc/apt/sources.list.d/homebridge.list> /dev/null

Update and install:

sudo apt-get updatesudo apt-get install homebridge

Package scripts workflow (preinst, postinst, postrm etc.):

https://wiki.debian.org/MaintainerScripts

Copyright (C) 2025 homebridge

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.