Repository navigation
Credential Extraction
Prepare controller credentials on your own device, then import selected HAP records or a native irestore keychain JSON export into Home Assistant.
Choose the method for your computer. Each option has its own complete section below. All tools listed here are free.
| Option | Platform | Method | Recommendation |
|---|---|---|---|
| 1 | macOS | iPhone Backup Explorer | Recommended. Graphical export from an encrypted iPhone/iPad backup. |
| 2 | macOS | Direct extraction wizard | Advanced / experimental. Temporarily requires SIP/AMFI changes. |
| 3 | Windows | irestore | Experimental. Command-line export from an encrypted iPhone/iPad backup. |
Recommended for macOS.
You need: an iPhone/iPad with access to the intended HomePods, its cable, a Mac running macOS 14+, the encrypted backup password, and iPhone Backup Explorer.
- Open Home on your iPhone/iPad and confirm access to the intended HomePods.
- Connect it to your Mac by cable. Unlock it and complete the normal Trust prompt if shown.
- In Finder, select the device → General. Choose to back up all device data to this Mac.
- Enable Encrypt local backup, retain its password, and select Back Up Now. An existing encrypted backup needs its existing password.
- After completion, open Manage Backups and check the timestamp and lock icon.
- Download and install iPhone Backup Explorer.
- Use Open Backup Folder… or Choose Backups Folder… to select the backup. Use the folder picker instead of broad Full Disk Access.
- Select the encrypted backup and enter its password in the application, never in HA.
- Open Passwords → Options → Show system items. Search for
com.apple.hap.pairingand expand System Items if needed. - Select only the matching HomeKit Pairing Identity and Paired HomeKit Accessory rows for your selected HomePods.
- Choose Export → Export Selected and save the CSV locally. Do not export unrelated passwords or whole sections.
Advanced, experimental alternative for direct extraction from an Apple silicon Mac.
Run the wizard on the Mac signed into the Apple Account that manages your HomePods. The HomePods must be visible in Home.
Security changes required: this route temporarily requires you to disable System Integrity Protection (SIP) and Apple Mobile File Integrity (AMFI). The wizard prints the commands and checks the results; security changes and restarts remain manual.
- Use an Apple silicon Mac and a native Terminal session, without Rosetta or running the wizard with
sudo. - Install Xcode or its Command Line Tools, plus Python 3.9 or newer.
- Have a valid Apple Development signing certificate. To create one in Xcode, open Settings → Accounts → Manage Certificates → + → Apple Development. Keep normal certificate trust checks enabled.
- Keep the export folder outside iCloud Drive, shared folders and Git repositories. Leave it in place on the same Mac until restoration is verified.
In Terminal, from a local folder outside cloud-synchronised/shared storage:
git clone https://github.com/barneyonline/ha-homepod-sensor-link.git
cd ha-homepod-sensor-link
bash scripts/macos_homekit_wizard.shRun bash scripts/macos_homekit_wizard.sh --help to see the command summary without starting extraction.
The wizard confirms prerequisites, compiles the bundled helper with protections enabled and saves the original boot arguments, including whether the setting was absent. Its private working folder is ~/HomePodSensorLink-Export, with directory permissions 0700 and credential/state file permissions 0600.
If compilation fails, stop with protections enabled. Otherwise, follow the displayed steps to enter macOS Recovery → Utilities → Terminal, temporarily disable SIP, return to normal macOS, apply the displayed AMFI boot argument and restart again. Use the wizard's commands for your saved settings.
After the instructed reboots, return to the same repository folder and rerun:
bash scripts/macos_homekit_wizard.shThe wizard verifies that the temporary settings are active in the running system. In Keychain Access, copy the complete name of your valid Apple Development certificate into the certificate-name prompt. Confirm signing and extraction when asked.
The helper reads only the HomeKit pairing access group and saves its output privately as ~/HomePodSensorLink-Export/homekit-keys.txt. It does not change HomeKit keychain records or accessory pairings. Keys are not printed to the terminal.
Follow the displayed restoration instructions immediately, including if extraction fails or is cancelled: restore the original boot arguments in normal macOS, return to Recovery to enable SIP, then restart. Keep the private working folder and its saved settings until restoration is verified.
Rerun the same wizard command after restoration. It checks SIP, the original boot arguments and the running kernel before reading the private dump.
The wizard automatically parses the extracted keys. If multiple records exist, choose controller identities and paired accessories by menu number; only identifiers are displayed. A sole record is selected automatically. Select only the records for the intended HomePods, with up to three controller identities and 64 accessories. If a record cannot be identified, stop rather than guess. You do not copy or type individual keys.
It writes the selected records to a private homepod-import-….json file and leaves its exact path visible on the final screen. The JSON is synced and read back before the temporary key dump is deleted. Failed writes or verification keep the dump. If cleanup is interrupted, rerunning the wizard verifies and reuses the recorded JSON and retries cleanup; changed files or unsafe permissions stop cleanup.
Signing certificates and the original HomeKit keychain records are retained.
To display the saved restoration instructions at any time after the original settings have been recorded, run from the same checkout:
bash scripts/macos_homekit_wizard.sh --restoreThis prints the instructions; you perform the privileged commands and restarts yourself. Restore protections even if extraction fails. Do not delete the private working folder before restoration is verified, or overwrite unrelated boot arguments.
Use irestore v0.4.0 to export readable keychain records from an encrypted local iPhone/iPad backup. It is free and open source.
You need: an iPhone/iPad with access to the intended HomePods, its cable, Apple's Apple Devices app or iTunes, the encrypted backup password, and irestore v0.4.0.
From the latest release, download the archive matching your PC.
Extract the archive to a local folder. Windows 11 can extract it in File Explorer; if your Windows version cannot, use tar -xzf "C:\path\to\archive.tar.gz" from a folder you choose.
- Open Apple's Apple Devices app, or iTunes if that is what you use for backups.
- Open Home on your iPhone/iPad and confirm access to the intended HomePods. Connect and unlock it, then complete the normal Trust prompt if shown.
- Select the device, then General in Apple Devices or Summary in iTunes. Choose to back up all device data to this computer.
- Enable Encrypt local backup, retain the password, and choose Back Up Now. An existing encrypted backup requires its existing password.
- Check the completed backup's timestamp. Open Manage Backups and use Show in Explorer if available. Otherwise, check
%USERPROFILE%\Apple\MobileSync\Backupfor Apple Devices/Microsoft Store iTunes, or%APPDATA%\Apple Computer\MobileSync\Backupfor traditional iTunes.
Choose the individual device-backup folder containing Manifest.plist, Manifest.db, Info.plist and the numbered subfolders. Supply that folder to irestore, not its parent Backup folder.
Apple's Windows backup instructions · Locate local backups.
The raw dump can contain passwords and keys unrelated to HomeKit. Use a new local folder outside OneDrive, shared folders and repositories.
Create a new working folder. Use a new folder name for a retry; do not reuse an old dump:
$work = Join-Path $env:LOCALAPPDATA "HomePodSensorLink-irestore"
New-Item -ItemType Directory -Path $work -ErrorAction Stop
Set-Location -LiteralPath $workCheck the folder's access permissions. Replace both example paths with the extracted executable and the individual backup folder:
& "C:\path\to\irestore.exe" "C:\path\to\device-backup-folder" dumpkeys "$work\keychain.json" > $null
if ($LASTEXITCODE -ne 0) { throw "Extraction failed. Keep the working folder private; do not import its output." }Enter the backup encryption password at the hidden prompt. Wait for completion. If extraction reports an error, stops unexpectedly or does not create a non-empty keychain.json, stop here. Keep failures private; do not upload the dump or failed.bin.
These commands are for v0.4.0, which takes the backup folder as its first argument. Do not substitute a device name or add a -path option. Reviewed command implementation.
All methods finish here. Use your selected HAP CSV/JSON, the wizard's JSON output, or irestore's complete keychain.json.
- Add HomePod Sensor Link, or use Reconfigure → Add or import devices on the existing entry. Select your HomePods.
- From a local HA administrator session, choose Paste a CSV or JSON export and paste the file’s contents unchanged (up to 2 MiB for irestore JSON, 128 KiB for other exports), or choose Enter controller credentials for the masked private-key form.
- Submit the native form. HA checks identities, key pairs, pins and permissions. Confirm fresh temperature/humidity readings; follow setup and retry guidance if incomplete.
After setup succeeds and fresh readings appear, delete the JSON/export file or move it to secure encrypted storage. Clear copied credentials from the clipboard, remove unnecessary export copies and keep backups protected. Never share keys, exports, backups, identifiers, the wizard's private working folder or unreviewed logs.
If blocked, report only application/OS versions, record counts and the integration's controlled error code.