HomeKit GUI

HomeKit GUI is a HACS-installable Home Assistant custom integration for managing the entity filter of an existing HomeKit Bridge from an admin-only sidebar panel.

It is designed for bridges that have grown beyond a comfortable configuration.yaml include/exclude list. The panel shows every entity, the effective filter result, exact include/exclude overrides, domain rules, and glob rules.

Features

• Native Home Assistant sidebar panel with mobile and dark-theme support.
• Search by entity ID, friendly name, domain, or source integration.
• Per-entity Default, Include, and Exclude controls.
• Include/exclude domain and entity-glob editors.
• Effective-filter preview using Home Assistant's filter precedence.
• Admin-only frontend and WebSocket write API.
• Optimistic concurrency check to prevent one browser overwriting another.
• Automatic snapshot and rollback for the ten most recent saves.
• Transactional bridge reload with automatic rollback after a failed apply.
• Preserves HomeKit pairing data and every non-filter option, including camera codec settings.
• Supports UI-created and YAML-imported HomeKit bridges.

Installation with HACS

Until the repository is included in the HACS default catalog:

1. Open HACS.
2. Select Custom repositories.
3. Add https://github.com/miamilabs/ha-homekit-gui as an Integration.
4. Install HomeKit GUI and restart Home Assistant.
5. Open Settings → Devices & services → Add integration.
6. Search for HomeKit GUI and select the existing HomeKit bridge.
7. Open HomeKit GUI from the sidebar.

HomeKit itself must already be configured and paired before HomeKit GUI is added.

YAML-managed bridges

Home Assistant imports YAML HomeKit configuration into a config entry at startup and when homekit.reload runs. HomeKit GUI does not rewrite configuration.yaml. Instead, after the first GUI save it stores the selected filter in its own config entry and reapplies that filter after startup or a YAML reload.

The YAML filter remains the baseline until the first GUI save. From then on, the GUI overlay is authoritative for the filter only. Other HomeKit options remain owned by HomeKit/YAML.

This behavior avoids fragile YAML rewriting and supports !include layouts. Removing HomeKit GUI leaves the last applied HomeKit options in place; on the next HomeKit YAML reload or Home Assistant restart, the YAML filter becomes authoritative again.

Safety model

• Only Home Assistant administrators can open the panel or call its commands.
• Saves update only options["filter"] on the selected HomeKit config entry.
• Pairing state, bridge identity, port, mode, devices, and entity_config are not replaced.
• homekit.unpair and homekit.reset_accessory are never called.
• Invalid entity IDs, domains, globs, unknown keys, stale revisions, and failed reloads fail closed.
• A filter preview means "selected by the Home Assistant filter." HomeKit may still reject unsupported entity types, hidden entities, or categorized entities unless explicitly included.

Compatibility

The initial release targets Home Assistant 2026.8 and newer and is verified against the Home Assistant 2026.9 API shape. HomeKit GUI uses public config entry, entity registry, storage, panel, and WebSocket APIs. Managing another integration's options is necessarily coupled to HomeKit's filter schema, so release testing against new Home Assistant versions is important.

Development

python3 -m compileall custom_components
python3 -m pytest
node --check custom_components/homekit_gui/frontend/homekit-gui-panel.js

See Architecture and Testing. Release history is available in the changelog.

License

MIT