icloud3: an iCloud device tracker built around a dashboard and an event log

Presence detection built from two sources at once

icloud3 is described in the repository as an advanced device tracker that uses Apple iCloud account and Home Assistant Mobile App data for presence detection and location based automations. The README is more specific about the mechanics: devices in the Family Sharing list and those in the HA Mobile App integration are trackable, and the device requests location data from Apple's iCloud Location Services while monitoring various Mobile App sensors and triggers.

From that it derives the values most presence setups actually need: battery level, location, distance, travel time and arrival at Home. Arrival at Home is the important one for automations, because a zone that flips on arrival is what lets a heating schedule or a lighting rule fire on presence rather than on a schedule.

The README acknowledges the official alternative directly, saying that although Home Assistant has its own official iCloud component, iCloud3 goes far beyond its capabilities. That claim is not verifiable from the documentation, but the shape of the feature list gives it some plausibility: a configurable polling cadence, per-device configuration, an event log and a dashboard builder are not things the official integration offers.

The project identifies itself as a custom integration rather than a fork of the official one, and it is distributed through HACS as a Custom Component. The repository topics list device-tracker, ha-ios, icloud, icloud-account, tracking, zone and zones, which describes a presence detection component rather than a general purpose iCloud API client.

Four parts, and the dashboard is the one you look at

The README describes the component as having four major parts, and the split is worth understanding because each one answers a different question.

The iCloud3 Device Tracker is the engine. It monitors the device location, determines when the device should be located next, and updates all the sensors. That second responsibility, deciding when to locate next, is the adaptive part of the design: the tracker is not polling every device on a fixed timer.

The Event Log is the diagnostic surface. It shows a device location, how location changes are handled, the results of location updates, errors, and startup information. For a component that infers presence from partial data, a readable log of how each change was interpreted is what makes it debuggable rather than mysterious.

Configure Settings is where you set up the tracked devices, the Apple Accounts, the iCloud3 Dashboards, sensors and other parameters. It is a configuration area rather than a YAML file, which is the main departure from how most Home Assistant integrations are set up.

The Dashboard Builder creates iCloud3 dashboards showing tracking results, battery information and the Event Log in several formats. The README adds that these dashboards can be customised with the Home Assistant Dashboard Editor and that the items and views can be copied and pasted into other dashboards, and that the Dashboard Builder is one of the Configure Settings screens rather than a separate tool.

That last point is the design choice that makes the whole thing usable. You build a view once, then reuse it elsewhere, instead of hand assembling sensor cards every time you want a presence view for a different part of the house.

Signing in to Apple happens in Home Assistant, then on a trusted device

The setup path is described as automated to make it as simple as possible: install the component, add an Apple Account, authenticate the Apple Account sign-in, import Apple Devices, build the iCloud3 Dashboard, end Configure Sessions, and start tracking.

The authentication step deserves a careful read because it involves your Apple Account credentials. On the Update Apple Accounts screen you enter your username, which is an email id, and your password, and log into your Apple Account. A sign-in notification is then displayed on your trusted device. On the next screen, Authenticate Apple Account Sign-in, you follow the instructions to enter the six digit authentication code or start the security key authentication process.

That two step structure is the point. The password goes into the component, and the second factor stays on Apple's side, delivered to a device you already trust. A user without an Apple device nearby cannot complete the flow, which is exactly the intended behaviour for an account that can locate all your devices.

The import step then uses the device information downloaded during sign-in to create iCloud3 devices. The next screen, iCloud3 Devices, lets you review and update the device configuration, with name, picture and Mobile App assignment given as examples of what can be changed.

One detail from the documentation worth knowing before you start: if you have hardware security keys, the flow offers the security key authentication path rather than only the code. Either path ends with the same result, an authenticated session that the component can use for location requests.

Installing the beta channel through a HACS custom repository

Two distributions exist and they are not the same thing.

The general release is iCloud3, available through HACS as a standard integration, with installation instructions in the User Guide. The repository also carries a Beta/Prerelease version, and to install that one you first have to register it as a Custom Repository in HACS, which takes four steps: open HACS, select the three dots in the upper right corner, select Custom Repositories, enter the repository name `gcobb321/icloud3_v3` with the category set to Integration, and select Add.

After the custom repository is registered, you search for and select the iCloud3 Apple Device Tracker Beta/Prerelease Version item on the main HACS screen, choose Download, and follow the normal steps for installing an integration through HACS.

The distinction matters because the release history shows a separate lineage for each. The stable line here is at v3.7.6, released on 2026-10-18, with v3.7.5 from 2026-09-08 and v3.7.4.1 from 2026-09-07. The README also links separate shields for the general release version and downloads and for the Beta/Prerelease version, which indicates that the two lines are released and versioned independently.

So the practical advice is to start on the general release and only move to the custom repository when you specifically want a prerelease feature, and to remember that adding a custom repository to HACS widens what your Home Assistant instance will pull code from.

First run ends with a dashboard and a cloud icon in the sidebar

The final steps of setup are about presentation, and the README is explicit that you should verify them.

After you exit the iCloud3 Configure Session, the iCloud3 Dashboard is built with your devices, added to the Home Assistant sidebar, and displayed as a cloud icon. Then you display the iCloud3 Dashboard, and if all went well you should see your devices and the Event Log.

That last clause is the acceptance test. A dashboard with empty device tiles and an Event Log full of errors means the account authenticated but the location side is not working, and the Event Log is where that shows up first. This is why the log is a first class component rather than a debug aid: it is the only place the internal decisions are visible.

The documentation covers more screens and parameters than the README reproduces. The User Guide is described as quite extensive and lives at the iCloud3 documentation site, with a chapter on installing and configuring iCloud3 for the first time. The README also notes that the documentation introduces the many features and components, highlights the configuration screens and parameters, and provides example screens, automations and scripts.

For someone deciding whether to install this, the example automations and scripts are the fastest way to judge whether the presence model matches what you want to build. Presence detection that produces a distance and travel time is more than a binary home or away, and whether you need that granularity is the question to answer before you commit.

Account credentials in a third party component are the real trade-off

Setting aside features, there is one decision that should be made consciously rather than by clicking through the setup wizard.

The setup asks for your Apple Account username and password inside Home Assistant. Your Apple account can locate every device in your family, and it is the same credential that protects your mail, your photos and your payment methods. Handing it to a custom component is a different proposition from handing it to a first party Apple service, even when the component is open source and MIT licensed.

There are partial mitigations, and the README points at them. The second factor stays on your trusted device, so the component cannot silently complete a fresh sign-in without you.

Still, the honest framing is that a Home Assistant instance running a custom component with your Apple password is a machine worth protecting: if the instance is exposed beyond your own network, or if you install other custom components from less careful sources, that credential is in reach.

The MIT licence covers the code, so you can read what it does with the credential and fork it if you want to change that behaviour. The repository layout supports that reading, with the implementation under `custom_components/` and a `v2_docs/` directory in the repository alongside the HACS metadata in `hacs.json`.

The last push was on 2026-10-20, two days after the v3.7.6 release, so the project is actively worked on. That cuts both ways: frequent releases mean fixes arrive quickly, and they also mean behaviour changes between versions, so pin the version if you depend on a specific detail.

Editorial conclusion

icloud3 suits a Home Assistant user with Apple devices who wants presence detection and location automations driven by iCloud and the Home Assistant Mobile App rather than by a single official integration with a narrow feature set, and it is the wrong choice if you do not want to hand an Apple account password to a third party component, since the setup asks for your Apple Account username and password on screen. Verify three things before you rely on it: that the Apple account you sign in with has the devices you want tracked in its Family Sharing list or in the HA Mobile App integration, that the sign-in flow completes on a trusted device, because the six digit authentication code is delivered there and not in Home Assistant, and that you have read the event log after the first run, since that log is where the component reports how it interpreted each location change.

Frequently asked questions

Official sources

1. gcobb321/icloud3 on GitHub
2. Issues
3. License: MIT
4. README
5. Releases