HomeKit Bridge¶

The built-in HomekitService runs a HAP-NodeJS bridge inside the automation engine. It translates every Zigbee2MQTT device tracked by the device registry into a HomeKit accessory in real time — no separate Homebridge process required.

Prerequisites¶

• DEVICE_REGISTRY_ENABLED=true — the service reads devices and their live state from the device registry. If the registry is not available the bridge skips startup and logs a warning.
• hap-nodejs is already bundled as a dependency of ts-home-automation. No additional installation is needed.

Registering the service¶

Pass a HomekitService factory to the services.homekit field in your entry point. The factory receives mqtt and deviceRegistry as extra arguments so there is no circular reference between the factory and the engine object:

import { createEngine, HomekitService, HOMEKIT_SERVICE_KEY } from "ts-home-automation";

const engine = createEngine({
  automationsDir: "./src/automations",
  services: {
    [HOMEKIT_SERVICE_KEY]: (_http, logger, mqtt, deviceRegistry) =>
      new HomekitService(mqtt, logger, deviceRegistry, {
        pinCode: "031-45-154",
      }),
  },
});

await engine.start();

Note: HomekitService uses a dedicated HomekitServiceFactory type (http, logger, mqtt, deviceRegistry) => HomekitService instead of the generic ServiceFactory<T>. The engine resolves mqtt and deviceRegistry before calling the factory, so both are guaranteed to be available.

Options¶

new HomekitService(mqtt, logger, deviceRegistry, {
  pinCode: "031-45-154",        // required — shown in the Home app when pairing
  bridgeName: "My Home Bridge", // optional, default: "TS-Home-Automation"
  port: 47128,                  // optional, default: 47128
  username: "CC:22:3D:E3:CE:F8",// optional, default: "CC:22:3D:E3:CE:F8"
  persistPath: "./homekit-persist", // optional, default: "./homekit-persist"
  bind: ["net1"],               // optional — restrict mDNS to specific interfaces
})

Pairing¶

1. Start the engine — the bridge is announced via mDNS automatically.
2. Open the Home app on iPhone/iPad, tap + → Add Accessory → More options.
3. Select the bridge (it will appear as bridgeName).
4. Enter the pinCode when prompted.
5. All supported Zigbee devices are exposed as individual accessories inside the bridge.

Supported device types¶

The bridge maps Zigbee2MQTT device capabilities to HomeKit services automatically:

Devices that expose none of the above capabilities are silently skipped.

Dynamic accessories¶

The bridge reacts to device registry events at runtime:

• Device joined — a new accessory is created and added to the bridge immediately.
• Device left — the accessory is removed from the bridge.
• State change — the accessory's characteristics are updated in real time so the Home app always shows the current state.

Multiple bridges¶

If you run multiple engine instances on the same network, each bridge must have a unique username (MAC address) and port:

// Instance A
new HomekitService(mqtt, logger, registry, {
  pinCode: "031-45-154",
  username: "CC:22:3D:E3:CE:F8",
  port: 47128,
});

// Instance B — different username and port
new HomekitService(mqtt, logger, registry, {
  pinCode: "031-45-155",
  username: "DD:33:4E:F4:DF:A9",
  port: 47129,
});

Status API¶

The service registers a route on the shared HTTP server:

Example response:

{
  "running": true,
  "bridgeName": "My Home Bridge",
  "port": 47128,
  "username": "CC:22:3D:E3:CE:F8",
  "persistPath": "./homekit-persist",
  "accessoryCount": 12
}

This endpoint is protected by the same HTTP_TOKEN bearer auth as all other /api/* routes.

Running in Docker / Kubernetes¶

Container networking & mDNS discovery¶

hap-nodejs advertises the bridge via mDNS (Bonjour) multicast so Apple devices can discover it on the local network. Docker bridge networks and Kubernetes pod network namespaces isolate multicast traffic — the bridge starts and runs correctly, but Apple Home cannot discover it.

Three options ranked by simplicity:

1. Host networking (simplest)¶

When using host networking: - Docker: remove networks / depends_on blocks (they conflict with host mode) and use localhost or host IPs for service references. - Kubernetes: MQTT_HOST must be an IP or hostname reachable from the host network, not a cluster-internal service DNS name.

2. Multus CNI + macvlan + bind (Kubernetes, no hostNetwork)¶

Attach a secondary network interface with a LAN IP to the pod using Multus CNI and a macvlan attachment. Then use the bind option to advertise mDNS only on that interface:

# NetworkAttachmentDefinition (applied once per namespace)
apiVersion: k8s.cni.cncf.io/v1
kind: NetworkAttachmentDefinition
metadata:
  name: lan-macvlan
spec:
  config: |
    {
      "cniVersion": "0.3.1",
      "type": "macvlan",
      "master": "eth0",
      "mode": "bridge",
      "ipam": {
        "type": "host-local",
        "subnet": "192.168.1.0/24",
        "rangeStart": "192.168.1.200",
        "rangeEnd": "192.168.1.210"
      }
    }

# Pod (from docs/deployment.md) — add the annotation and bind option:
apiVersion: v1
kind: Pod
metadata:
  name: home-automation
  annotations:
    k8s.v1.cni.cncf.io/networks: lan-macvlan
spec:
  # hostNetwork: true  ← NOT needed with Multus
  containers:
    - name: engine
      env:
        - name: HOMEKIT_BIND
          value: net1   # the macvlan interface (first attachment = net1)

// Pass the bind value from the environment into HomekitServiceOptions:
bind: process.env.HOMEKIT_BIND?.split(",") ?? undefined,

The pod keeps its cluster network (eth0) for MQTT and HTTP while mDNS goes out the macvlan interface (net1) directly onto the LAN. Apple devices discover the bridge at the macvlan IP.

3. mDNS repeater (any environment)¶

If neither host networking nor Multus is available, run an mDNS repeater/proxy (e.g. avahi-reflector in reflection mode) to forward multicast between the container network and the host network. This approach is more complex and not covered here.

Pairing data persistence¶

hap-nodejs uses node-persist for storage, and older versions of node-persist resolve relative paths against their own __dirname inside node_modules rather than process.cwd(). In a container this often points to a read-only layer, causing an EACCES: permission denied crash.

HomekitService resolves the configured persistPath to an absolute path before handing it to hap-nodejs, so ./homekit-persist becomes /app/homekit-persist instead of /app/node_modules/node-persist/src/storage/homekit-persist.

For production deployments it is recommended to mount a dedicated volume and use an absolute path explicitly:

new HomekitService(mqtt, logger, registry, {
  pinCode: "031-45-154",
  persistPath: "/data/homekit-persist",
});

Make sure the container user has write access to that directory.

CLI dashboard¶

The interactive ts-ha dashboard includes a dedicated HomeKit tab (key 6) showing:

• Bridge running/stopped status
• Number of registered accessories
• Full configuration (bridge name, HAP port, MAC address, pairing PIN, persist path)

When the service is not configured the tab displays a setup hint. The Overview tab (key 1) also shows a HomeKit: running / stopped badge whenever the service is present.

Web UI¶

The browser dashboard includes a HomeKit page in the navigation sidebar. It shows:

• Status cards: bridge running state, accessory count, HAP port, paired/offline badge
• A configuration panel with all bridge settings

When the service is not configured an informational notice is shown explaining how to register it.