Homebridge

Last reviewed Aug 26, 2026 · 841 words

If you already run Home Assistant, you almost certainly do not need Homebridge. Home Assistant's built-in HomeKit Bridge integration exposes its entities to Apple Home directly, and running both means two bridges arguing over the same devices. Homebridge is for the other household: the one that wants Apple Home as the only interface, has no interest in a second dashboard, and needs a translator for the 15-pound smart plug Apple refuses to see. For that household it is close to perfect, and on a Raspberry Pi it idles in about 256 MB of RAM.

One container, one rule you would normally never break

Homebridge is a Node.js server (TypeScript, Apache-2.0, 25,467 stars, around since 2014) that pretends to be a HomeKit accessory bridge. HomeKit discovers bridges over mDNS, and mDNS does not cross Docker's bridge network, so the container has to run with host networking. Every other advice you have read about isolating containers is correct and this is the exception:

services:
  homebridge:
    image: homebridge/homebridge:latest
    network_mode: host
    volumes:
      - ./homebridge:/homebridge
    restart: unless-stopped

The web UI comes up on port 8581, the HomeKit accessory protocol on 51826, and the first screen shows a QR code that the Home app scans to pair. If the Home app cannot find the bridge, the cause is host networking, a VLAN between the phone and the server, or a firewall dropping multicast, in that order of likelihood. Install on bare Debian works the same way without the container question, and the project publishes a ready-made Raspberry Pi image if you want to skip the OS entirely.

Plugins: verified badge first, child bridge always

Everything Homebridge does for a specific device comes from an npm package named homebridge-something, and there are thousands. The "verified" badge in the plugin search means the maintainers have checked it installs cleanly and follows the plugin API; it is the closest thing to a quality signal, and I start there every time. Then, for any plugin that talks to a cloud service or a flaky device, enable it as a child bridge in the plugin's settings. A child bridge runs the plugin as its own process with its own pairing, so when the cheap-brand cloud API times out and the plugin hangs, the rest of your home keeps responding and you restart one plugin instead of the whole server. Two more limits to know: HomeKit allows just under 150 accessories per bridge, so big installs split across child bridges anyway, and a plugin that exposes 40 accessories for a single hub device will eat that budget fast.

The pairing file is the backup that matters

Pairing state lives in the persist directory inside the volume, alongside config.json. Lose it, and the Home app still shows the bridge but nothing responds; the fix is deleting the bridge in Home and re-pairing, which throws away every room assignment, scene and automation that referenced those accessories. Back up the entire /homebridge volume, or use the backup archive the UI exports, before any upgrade. Changing the bridge's username (the MAC-style identifier in the config) has the same effect as losing the file, so leave it alone.

Remote access and automations need Apple hardware

Homebridge has no cloud and no remote-access feature, and it does not need one. A HomePod, HomePod mini or Apple TV acting as a Home hub handles remote access and runs automations even when your phone is out of the house. Without a hub, everything works on the local network and nothing works away from it, and time-based automations do not run at all. Budget for one before blaming the software.

Where Homebridge stops

Cameras are the first wall. Video plugins exist, but HomeKit Secure Video is a different beast, and Scrypted is the tool people who care about cameras end up on. Matter is the second: Homebridge speaks HomeKit only, and Matterbridge is the same idea rebuilt for the Matter protocol, useful if Google or Amazon devices share the house. The third is scope: the moment you want a dashboard, history graphs or automations more complex than "when this, do that", you are describing Home Assistant, which can then present everything to Apple Home itself. Plenty of people run Homebridge for 2 years and migrate; the plugins mostly have Home Assistant integrations waiting on the other side.

What I'd do

Docker with network_mode: host on whatever small box is always on, verified plugins only, every plugin a child bridge, the volume in the nightly backup, a HomePod mini as the hub. Keep the accessory count below 100 per bridge and resist plugins that need a cloud login when a local alternative exists. If the household is all-Apple and wants nothing beyond the Home app, that setup runs for years with a monthly npm update. If you find yourself wanting graphs, start with Home Assistant instead and let it be the bridge.