{"id":50724325,"url":"https://github.com/mikenemat/ha-lockbridge","last_synced_at":"2026-06-16T01:01:57.022Z","repository":{"id":361037347,"uuid":"1252075683","full_name":"mikenemat/HA-LockBridge","owner":"mikenemat","description":"Bridge Apple Home–paired locks into Home Assistant without losing HomeKey, Siri, or Apple Home. macOS app on the Mac App Store + a companion HA integration.","archived":false,"fork":false,"pushed_at":"2026-06-05T22:31:20.000Z","size":310,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T00:08:49.386Z","etag":null,"topics":["hacs","home-assistant","homeassistant","homekey","homekit","homekit-bridge","mac-catalyst","swift"],"latest_commit_sha":null,"homepage":"https://apps.apple.com/app/id6774393748","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikenemat.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T06:59:22.000Z","updated_at":"2026-06-05T22:31:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mikenemat/HA-LockBridge","commit_stats":null,"previous_names":["mikenemat/ha-lockbridge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mikenemat/HA-LockBridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikenemat%2FHA-LockBridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikenemat%2FHA-LockBridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikenemat%2FHA-LockBridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikenemat%2FHA-LockBridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikenemat","download_url":"https://codeload.github.com/mikenemat/HA-LockBridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikenemat%2FHA-LockBridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34134633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacs","home-assistant","homeassistant","homekey","homekit","homekit-bridge","mac-catalyst","swift"],"created_at":"2026-06-10T03:00:48.385Z","updated_at":"2026-06-16T01:01:56.902Z","avatar_url":"https://github.com/mikenemat.png","language":"Swift","funding_links":["https://github.com/sponsors/mikenemat"],"categories":[],"sub_categories":[],"readme":"# HA-LockBridge\n\n\u003e A Mac Catalyst bridge that exposes Apple-Home-paired locks to HomeAssistant\n\u003e **without losing HomeKey, Apple Home, or any other native Apple integration**.\n\nMost HomeKit-to-HomeAssistant integrations require you to *unpair* your lock from\nApple Home and pair it with HA instead — which kills HomeKey, family sharing, and\nSiri control. HA-LockBridge takes a different approach: a small macOS app\nrunning on any always-on Mac (mini, VM, or iCloud-signed-in laptop) registers\nitself as a *second* HomeKit controller in your home and exposes its accessories\nto HA over a local HTTP + WebSocket API. The lock stays paired with Apple Home;\nHA just gets read/write access through the bridge.\n\nOther solutions — virtual/template switches and automations that sync states and\nactions between the two ecosystems — provide basic functionality, but are\nbrittle. They rely on extensive manual configuration in *both* HomeKit and Home\nAssistant, and often fail silently or drift out of sync after minor outages and\ncommunication glitches. They also become frustrating to debug as you scale up to\n5–10 locks or more on a larger property. If you only have one or two locks, you\nshould absolutely attempt that before going all-in on this option — here's a good\n[example writeup](https://nils.schimmelmann.us/2025-03-19-schlage-encode-plus-home-assistant/).\n\n\u003e [!CAUTION]\n\u003e **HA-LockBridge has three hard environment requirements. Read these before you start.**\n\u003e\n\u003e - **An always-on Mac.** It's a macOS app — it must run on a Mac (mini, iMac,\n\u003e   any Mac left powered on) that stays awake, is signed into your Apple Home's\n\u003e   iCloud account, and runs **macOS 15 (Sequoia) or newer**. There is no iOS,\n\u003e   iPad, Apple TV, or standalone-hardware version. See\n\u003e   [Requirements](#requirements).\n\u003e - **Foreground.** Apple's HomeKit lets an app\n\u003e   control locks *only* while it is the **frontmost, active app** — an Apple\n\u003e   limitation with no workaround. So HA-LockBridge grabs focus every time Home\n\u003e   Assistant sends a lock command. **A dedicated Mac mini is strongly\n\u003e   recommended**; on a Mac you actively use, it will jump to the front on every\n\u003e   lock action. It will restore focus within a few seconds.\n\u003e - **An active display device.** A headless Mac with no display has no window\n\u003e   context, so the app can't take focus and lock control silently fails. You\n\u003e   need a **physical monitor, an HDMI dummy plug, or display software like\n\u003e   [BetterDummy / BetterDisplay](https://github.com/waydabber/BetterDisplay)**\n\u003e   attached or running at all times. Screen Sharing alone is *not* enough — it\n\u003e   only provides a display context while the session is open.\n\n## Get the macOS app\n\n**The macOS bridge is distributed exclusively through the Mac App Store.** That\nis the only supported way to install it — there is no download, installer, or\nnotarized release here on GitHub. Apple requires the HomeKit entitlement to ship\nvia the App Store on macOS (Developer ID / notarized distribution is not\npermitted for HomeKit apps), so the App Store is the one and only channel.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://apps.apple.com/app/id6774393748\"\u003e\n    \u003cstrong\u003e➜ Download HA-LockBridge on the Mac App Store\u003c/strong\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nThe companion **Home Assistant integration** is what lives in this repo (see\n[Quick start](#quick-start) below) — install that via HACS.\n\n\u003e **Advanced users** can build the macOS app themselves with Xcode instead — the\n\u003e full source is in [`macos-app/`](macos-app/). Note that a build signed with a\n\u003e free Apple Developer account is only valid for **7 days**; after that macOS\n\u003e blocks it from launching until you rebuild and re-sign. The Mac App Store build\n\u003e has no such expiry, which is why it's the recommended path for everyone else.\n\n## Demo\n\nhttps://github.com/user-attachments/assets/c5c490f5-7cfa-4938-8f27-a8e1e7de5c62\n\n## Built for ThorBolt X1, works with any HomeKit lock\n\nThe integration was developed with [ThorBolt X1](https://thorbolt.com) (sold by\nSleekpoint Innovations) in mind — it's the lock the author owns and the one that\nbenefits most from this architecture because of HomeKey support. Any HomeKit\nlock works, though — August, Yale, Aqara, Level, **Schlage Encode Plus**,\nand others all expose the standard `HMServiceTypeLockMechanism` the bridge\nreads and writes.\n\nSeveral of those locks *do* have first-party Home Assistant integrations, but\nthey're typically **cloud-polling** (HA talks to the manufacturer's servers,\nwhich talk to the lock) — that means an internet dependency, polling latency,\nand another account to keep alive. This bridge is **local-push**: state changes\narrive over your LAN the moment HomeKit sees them, with no cloud in the path.\nIf your lock has HomeKey (like the ThorBolt X1 or Schlage Encode Plus), the\nbridge is also the only way to get it into HA *without unpairing it from Apple\nHome and losing HomeKey* — see the [scope FAQ](#faq-why-only-locks) for why\nthat trade-off matters.\n\nWhen HA discovers the bridge, the device-selection screen splits locks into\n**ThorBolt X1 locks (recommended)** and **Other HomeKit locks** — ThorBolts\nchecked by default, others opt-in.\n\n## Architecture\n\n```\n                       ┌──────────────────────────────────────┐\n                       │  Apple Home (iCloud-synced)          │\n                       │  ┌──────────┐ ┌────────────┐         │\n   HomeKey iPhone ──── │  │ ThorBolt │ │ HomePod    │         │\n   (NFC unlock)        │  │   X1     │ │ (resident) │         │\n                       │  └────┬─────┘ └─────┬──────┘         │\n                       └───────┼─────────────┼────────────────┘\n                               │             │\n                               └─────HAP─────┤\n                                             │\n                                             ▼\n                       ┌──────────────────────────────────────┐\n                       │  Mac running HA-LockBridge.app       │\n                       │  (signed into your iCloud)           │\n                       │                                      │\n                       │  • Mac Catalyst Swift app            │\n                       │  • Uses HMHomeManager as a 2nd       │\n                       │    controller in your Apple Home     │\n                       │  • Advertises self via Bonjour       │\n                       │  • Serves HTTP + WS on :8765         │\n                       └──────────────────┬───────────────────┘\n                                          │\n                              HTTP + WebSocket (LAN, token auth)\n                                          │\n                                          ▼\n                       ┌──────────────────────────────────────┐\n                       │  Home Assistant                      │\n                       │  custom_components/ha_lockbridge│\n                       │                                      │\n                       │  • Zeroconf auto-discovers bridge    │\n                       │  • Click-to-pair (no token typing)   │\n                       │  • LockEntity per lock (full lifecycle: │\n                       │    locked / locking / unlocked /     │\n                       │    unlocking / jammed)               │\n                       │  • Battery + low-battery sensors     │\n                       └──────────────────────────────────────┘\n```\n\n## What's in this repo\n\n| Path | What it is |\n|---|---|\n| [`macos-app/`](macos-app/) | The Mac Catalyst app. SwiftNIO HTTP + WebSocket server, Bonjour advertising, in-app pairing UI, HomeKit framework integration. |\n| [`custom_components/ha_lockbridge/`](custom_components/ha_lockbridge/) | The HA custom integration. Auto-discovery via zeroconf, two-step pairing flow, lock/sensor/binary_sensor entities. |\n\nEach has its own README with build/install details.\n\n## Quick start\n\n### 1. Install the macOS bridge from the Mac App Store\n\nInstall **[HA-LockBridge from the Mac App Store](https://apps.apple.com/app/id6774393748)**\nonto a Mac that stays powered on and is signed into the iCloud account your\nApple Home lives on. On first launch:\n\n1. Click **Allow** on the macOS Home Data access prompt.\n2. In the app window, click **Open Login Items…** under *Start at Login* and\n   add **HA-LockBridge** in System Settings → General → Login Items, so the\n   bridge auto-launches with your Mac. (macOS doesn't let a Mac Catalyst app add\n   itself, so this is a quick one-time manual step.)\n\nThe bridge runs as a normal foreground app — a Dock icon and a single\nalways-visible window showing **\"Waiting for Home Assistant to pair\"**. There\nis no menu-bar icon; all controls (Start at Login, Reset Pairing, Quit) live\nin the window.\n\n\u003e **Contributors:** build instructions for the macOS app are in\n\u003e [`macos-app/README.md`](macos-app/README.md). (Self-signing caveats are\n\u003e covered under [Get the macOS app](#get-the-macos-app) above.)\n\n### 2. Install the HA integration\n\nPick whichever fits:\n\n- **HACS (recommended):** add this repository as a custom integration repository in [HACS](https://hacs.xyz), then install **HA-LockBridge**. HACS handles updates for you.\n- **Manual — release zip:** download the latest `ha_lockbridge-\u003cversion\u003e.zip` from the [**Releases page**](https://github.com/mikenemat/HA-LockBridge/releases/latest), unzip it, and copy the resulting `ha_lockbridge` folder into `\u003cconfig\u003e/custom_components/`.\n- **Manual — from source:** copy the folder straight out of this repo:\n  ```bash\n  scp -r custom_components/ha_lockbridge \\\n    \u003cyour-ha-host\u003e:/config/custom_components/\n  ```\n\nRestart Home Assistant. Within ~10 seconds, **Settings → Devices \u0026 Services**\nshows a discovered **HA-LockBridge** card.\n\n### 3. Pair\n\nClick **Configure** on the discovered card → **Submit**. The bridge's window\nswitches to a pairing request with **Approve / Deny** buttons. Click **Approve**.\nHA's flow advances to the device-selection screen with your ThorBolts pre-checked.\n\n## What survives without intervention\n\n- **Mac rename or IP change** → mDNS announces the new hostname for the same UUID; HA's stored entry auto-updates.\n- **HA restart** → token persists in HA's config entry; bridge has it in `paired_clients`; reconnect is silent.\n- **Bridge restart** → same UUID, same tokens; HA reconnects silently.\n- **Network blip** → exponential-backoff reconnect loop in HA's client.\n- **Multiple HA instances** → each pairs independently and gets its own token.\n\n## Requirements\n\n| Component | Requirement |\n|---|---|\n| Bridge host | An **always-on, ideally dedicated Mac running macOS 15 (Sequoia) or newer**, signed into the iCloud account your Apple Home lives on, on the same LAN as a HomeKit resident (HomePod / Apple TV / iPad). It must stay awake, logged in, and with **HA-LockBridge as the frontmost app** — it runs as a visible foreground app and keeps the display awake. Using that Mac for other apps will delay lock commands. |\n| HomeAssistant | **2026.3+ recommended** — that release added the brand-icon proxy API the integration's logo uses. Manual installs on older HA versions still work fine; only the integration's logo won't appear. (HACS enforces 2026.3.0 as a hard minimum via `hacs.json`, so use the manual install to run on an earlier version.) |\n| Network | mDNS / Bonjour must traverse between the bridge host and HA. If HA runs in Docker without `--network=host`, mDNS discovery may need extra config. |\n\n## Caveats\n\n- **The bridge is a controller, not a resident**: it needs an existing HomeKit resident (HomePod / Apple TV / HomePod mini / iPad) on the same network to relay commands when not on the local LAN. If you have those (and you do, if HomeKey works), nothing to configure.\n- **Bridge must run in a GUI user session, foreground**: HomeKit access requires a logged-in user, and prompt lock *control* requires the app to be frontmost. On a dedicated Mac, enable auto-login + Start at Login so the bridge comes back frontmost after a reboot.\n- **Unavailable vs. optimistic-write tension**: when HomeKit reports a lock as unreachable (`reachable=false`), the HA lock entity goes **unavailable** — yet the bridge will *still accept and queue a write* and heal it the moment the lock wakes (it retries for 90s on an exponential backoff). So an automation that bails on \"unavailable\" may skip a command the bridge would actually have delivered. If you want a lock command to always be *attempted*, call it regardless of the entity's availability; the bridge does the right thing in the background.\n\n## Dedicated appliance Mac setup\n\nThe bridge is happiest on a Mac you don't otherwise touch (a Mac mini is ideal —\nsee why under [Requirements](#requirements) and the foreground caveat above).\nDo these once, in order, to turn that Mac into a hands-off appliance:\n\n1. **Install from the Mac App Store** and launch it once so the HomeKit access\n   prompt appears — click **Allow**.\n2. **Turn off FileVault** (System Settings → Privacy \u0026 Security → FileVault).\n   FileVault is **on by default on new Macs**, and it *blocks auto-login* — with\n   it on, the Mac sits at the disk-unlock screen after a reboot and the bridge\n   never starts. (This is a deliberate trade-off for a dedicated, physically\n   secured appliance; don't do it on a laptop you carry around.)\n3. **Enable automatic login** for the bridge's user account (System Settings →\n   Users \u0026 Groups → Automatically log in as). Now a reboot lands you logged in.\n4. **Add HA-LockBridge to Login Items** so it auto-launches: in the app window\n   click **Open Login Items…** under *Start at Login*, then add **HA-LockBridge**\n   under System Settings → General → Login Items. (Mac Catalyst apps can't\n   register themselves, so this is a one-time manual step.)\n5. **Disable automatic screen lock / \"Require password after sleep\"** (System\n   Settings → Lock Screen). A locked screen has no foreground app, so lock\n   *control* fails. Lock the screen *manually* with Control-Command-Q only when\n   you walk away and don't need writes for a while.\n6. **Turn off Fast User Switching** (System Settings → Control Center → Fast\n   User Switching → off), or at least never switch away from the bridge's\n   session — switching users backgrounds it and breaks writes.\n7. **Restart after a power failure** (System Settings → Energy → \"Start up\n   automatically after a power failure\"). Combined with auto-login + Login\n   Items, a power blip brings the bridge all the way back unattended.\n8. **Give it a display context.** A headless Mac can't take focus, so the app\n   can't control locks. Attach a real monitor, an **HDMI dummy plug**, or run\n   **[BetterDummy / BetterDisplay](https://github.com/waydabber/BetterDisplay)**\n   as a virtual display. Screen Sharing alone is *not* enough — it only provides\n   a display while the session is open.\n9. **Leave App Store automatic updates on** (System Settings → App Store → \"App\n   Updates\") so the bridge stays current without you logging in to update it.\n\n## FAQ\n\n\u003ca id=\"faq-why-only-locks\"\u003e\u003c/a\u003e\n**Why is this locks-only? Couldn't it bridge all my HomeKit accessories?**\nOn purpose. Locks are the one HomeKit category where the *normal* HA path —\nunpairing the accessory from Apple Home and pairing it with HA's\n`homekit_controller` instead — carries a real cost: it **breaks HomeKey** (and\nApple Home, Siri, and family sharing) for that lock. For lights, switches, and\nsensors that cost is near zero, so those are better served by HA's native\nintegrations or the manufacturers' own. Scoping to locks keeps the bridge small,\nkeeps its security surface (it can actuate *door locks*) auditable, and avoids\nreinventing a general-purpose HomeKit bridge that HA already has a better answer\nfor. See [What this project IS and ISN'T](CLAUDE.md) for the full rationale.\n\n**Should I use a dedicated Apple ID for the appliance Mac?**\n**Recommended, yes.** The bridge needs the Mac signed into the iCloud / Apple\nHome account your locks live on, and that account is logged in unattended on a\nmachine running with auto-login and no screen lock (see the appliance checklist\nabove). Rather than expose your primary Apple ID that way, create (or reuse) a\n**dedicated Apple ID**, invite it to your Apple Home as a **member** (Home app →\nHome Settings → invite — member access is enough to control the locks), and sign\n*that* account into the appliance Mac. If the appliance is ever compromised, you\nrevoke one home invitation instead of rotating your main Apple ID.\n\n## License\n\nMIT — see [LICENSE](LICENSE). Third-party attribution in [NOTICE.md](NOTICE.md).\n\n## Support this project\n\nHA-LockBridge is free and open source. If you find it useful, donations are\nwelcome to help cover the **$99/year Apple Developer Program** fee that keeps\nthe macOS app on the Mac App Store — you can\n[**sponsor the project on GitHub**](https://github.com/sponsors/mikenemat).\nEntirely optional, and much appreciated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikenemat%2Fha-lockbridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikenemat%2Fha-lockbridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikenemat%2Fha-lockbridge/lists"}