Skip to main content

How the app handles your data

The companion app is built around a simple idea: your data belongs to you, and it stays with the Home Assistant instance you choose to connect to. The app talks directly to your Home Assistant instances, and the information it collects about your device is sent to them and nowhere else. A few features rely on outside services to work properly: push notifications, optional crash reporting, and a small number of sensors. Each of those outside services is described below, so you can see exactly what leaves your device.

This page explains what that means in practice, what information can leave your device, and how to control or disable what gets shared.

You are in control of your data​

The sensor values, location, and other information the app collects are sent to your Home Assistant instance, the same instance you log in to. If you connect the app to more than one instance, you decide for each instance, what information it receives:

  • Location: you can send your exact location, only the name of the zone you are in, or nothing at all. See Location for the per-instance options on Android and iOS.
  • Sensors: how much control you have depends on the platform. Android On Android, you can enable or disable each sensor individually, and choose which sensors report to a given Home Assistant instance. iOS On iOS, you choose whether an instance receives all enabled sensors or none. See Sensors.

Because each connected Home Assistant instance is configured separately, turning something off in one Home Assistant instance never affects what another instance receives.

No advertising or usage tracking​

The app does not show advertising, does not monitor your behavior for marketing purposes, and does not include third-party usage analytics. The only optional report it can send is the crash report described below. It goes to Sentry, a third-party crash-reporting service that the app developers use to diagnose bugs, and it is only sent by the full flavor of the Android app. The minimal flavor sends no reports of any kind. On iOS iOS, any sharing of crash and usage analytics follows the choice you made in your device's diagnostics settings. See Crash reporting and diagnostics for details.

Default settings for a new Home Assistant instance​

When you connect the app to a new Home Assistant instance, it starts with sensible defaults that you can change afterward:

  • A small set of sensors is enabled to begin with, such as battery information, together with any sensors you granted permission to during onboarding. Most other sensors start disabled until you turn them on. See Sensors for the full list and how to manage them.
  • Android Remotely control app & device is enabled, so the instance can manage sensors and send notification commands that control the app from the start. See Letting a Home Assistant instance control your app and device below to change this.

How the connection between the app and your instance is encrypted (HTTPS and HTTP)​

If you connect over HTTPS, everything between your device and Home Assistant is encrypted by the connection itself, which is why an HTTPS address is recommended. See Connection security level for how the app handles unencrypted addresses.

If you connect over HTTP (an unencrypted connection), the two platforms differ in how they protect the data the app sends, such as sensor and location updates:

  • Android The Android app does not encrypt these payloads and relies on the connection. Over a plain HTTP connection, the sensor and location data it sends are transmitted in clear text and could be read by anyone able to observe the network.
  • iOS The iOS app encrypts these payloads (such as sensor and location data) using a secret it shares with your instance when the app is first registered. The data stays encrypted even when the underlying connection is plain HTTP. This payload encryption is not a replacement for HTTPS, though: your login and other traffic are only protected when the connection itself is encrypted.

On either platform, use an HTTPS address whenever you can, and if you must use an HTTP address, restrict it to your home network with the Most secure connection security level.

To set up an encrypted HTTPS connection to your instance, refer to the documentation on Remote access to Home Assistant. The simplest option is to use Home Assistant Cloud, which gives you an encrypted address without any certificate setup.

note

If you access your Home Assistant instance remotely via Home Assistant Cloud, your connection is encrypted and relayed through Nabu Casa's servers. That service is covered by the Home Assistant Cloud privacy policy.

Notifications​

Push notifications are the only feature that sends message content outside your Home Assistant instance. The app delivers them through Google's Firebase Cloud Messaging. Since the notification content is not encrypted and passes through Google's servers on its way to your device, Google could, in principle, read it.

How you avoid sending notification data to Google depends on your platform:

  • Android The full flavor has no in-app way to opt out of Firebase. You can still reduce its use, though: if you set up Local Push, your instance delivers notifications directly over a WebSocket connection, and Firebase only steps in as a fallback when that connection is unavailable. To avoid Google entirely, use the minimal flavor (from F-Droid or GitHub), which always uses Local Push and never Firebase.
  • iOS You can opt out of Firebase in the app's privacy settings. Notifications will then stop working.

For the full explanation and the rate limits, see Privacy, rate limiting and security.

Sensors that use external services​

Most sensors read information from your own phone or tablet and send it only to your instance. A few need an outside service to do their job, and they only run if you choose to enable them:

  • The geocoded location sensor turns your coordinates into a readable address. On Android Android this uses the device's built-in geocoder, and on iOS iOS it uses Apple's Core Location services.
  • Android The public IP sensor (sensor.public_ip) asks a third-party service (ipify) to report your device's public IP address.

See Sensors for the full list and the details of each one.

Crash reporting and diagnostics​

How crash data is reported depends on the platform:

  • Android On Android, two independent systems can report a crash: the crash and usage data collected by the app store, and the app's own crash reporting. You control each one separately.
  • iOS On iOS, only the app store collection applies.

Each of these reporting methods is described below.

Crash and usage data collected by the app stores​

Aside from anything the app does, the store you installed it from can gather its own crash reports and basic usage data. You control this through an operating system setting, not through the app. This data collection is handled by Google or Apple under their own privacy policies, and applies to apps in general, not only to Home Assistant.

  • Android If you installed from the Google Play Store and have turned on the device setting to share usage and diagnostics data, Google Play receives crash and application not responding reports along with basic stability and usage statistics. Developers see only aggregated reports in the Play Console. You can change this in your device settings under Google > Usage & diagnostics (the exact location varies by device). The minimal flavor installed from F-Droid or GitHub is not distributed through Google Play and is not covered by this collection.
  • iOS If you have turned on Share With App Developers in the Settings app under Privacy & Security > Analytics & Improvements, Apple shares aggregated crash and app-usage analytics with the developers through App Store Connect. Only data from users who opted in is included, and it is aggregated to avoid identifying individuals.

Crash reports sent by the app Android​

This crash reporting is specific to the Android app. To help find and fix bugs, the full flavor of the Android app can send a report to Sentry, when the app crashes. Reports are accessible only to the Home Assistant app developers and are handled under Sentry's privacy policy. This is the version distributed through the Play Store; the minimal flavor contains no crash reporting at all. For the difference between the two, see Android flavors.

Crash reporting is enabled by default in the full flavor, and you can turn it off at any time under Settings > Companion app in the Crash reporting setting.

A crash report is limited to technical information about the app and the device. It includes:

  • The app version and build.
  • The device model, manufacturer, and Android version.
  • The technical details of the crash itself, such as the stack trace.
  • A short trail of recent app and system events leading up to the crash, to help reproduce it.
  • An anonymous identifier generated by Sentry.

A crash report does not include any personal or home information. It never includes:

  • Your Home Assistant instance address or connection details.
  • Access tokens, passwords, or other credentials.
  • Content from your dashboards, entities, or notifications.
  • Screenshots or a capture of what was on screen.
  • Your email address or account name.

Connection problems are also never reported: errors such as a lost connection, a failed TLS handshake, or an unreachable host are ignored on purpose, since they describe your network rather than a bug in the app.

note

This is separate from the Show and share logs option used for troubleshooting, which you can use yourself. Those device logs may contain sensitive details such as your Home Assistant instance address, so review them before sharing.

Letting a Home Assistant instance control your app and device Android​

This setting is specific to the Android app. Each Home Assistant instance you connect to has a per-instance setting named Remotely control app & device, described in the app as Allow this server to enable and manage sensors and send notification commands. This setting determines whether that Home Assistant instance can reach back into the app and your device, both managing which sensors are enabled and sending notification commands that control the device, rather than only receiving the data the app sends to it.

You can find it on Android under Settings > Companion app > Server & devices, by opening the settings for the Home Assistant instance you want to configure. It is enabled by default.

When the remote control setting is enabled (the default)​

The Home Assistant instance is trusted, and it can:

  • Enable and disable the app's sensors. If you enable or disable one of the app's sensor entities from within Home Assistant, the app applies that change on its next sync.
  • Send notification commands that act on the app or device. These are notification commands that do more than show a message, such as toggling Do Not Disturb, changing the ringer mode or volume, controlling Bluetooth, turning the flashlight on, adjusting screen brightness, switching high-accuracy location mode, launching an app, or requesting a location update.
tip

A sensor that needs additional permissions, such as location or health data, can never be turned on by the Home Assistant instance alone. It always requires an action on the Android device. Instead of enabling such a sensor, the app keeps it disabled and shows a notification asking you to grant the permission. Tapping that notification opens the sensor's settings page so you can allow it there. This prevents a Home Assistant instance from enabling a sensitive sensor without your consent.

When the remote control setting is disabled​

The Home Assistant instance is no longer trusted to change the app or your Android device. Two things follow:

  • Your choices in the app take priority for sensors. Which sensors are enabled is then controlled only from within the companion app on your Android device. If you try to enable or disable a sensor for that instance from Home Assistant, the app changes it back to match your in-app setting at the next sync. For example, if a sensor is enabled in the app and you disable it from the instance, the app re-registers the sensor, and it becomes enabled again the next time your companion app syncs.
  • Notification commands that control the app or Android device are ignored. They are rejected, while ordinary notifications, including text-to-speech and clearing notifications, keep working as usual.

Disable this setting for any Home Assistant instance you do not want to be able to change settings on your Android device, while still allowing the app to send it sensor and location data as you've configured.

Removing your data and disconnecting​

Because the app only sends data to your own Home Assistant instance, you can stop sending data and delete what your instance has already stored at any time. Crash reports and notification delivery are handled separately. See Notifications and Crash reporting and diagnostics.

  • To stop sending data from a device, open that Home Assistant instance's settings in the app. Turn off the location and sensor options described above, or remove that Home Assistant instance from the app entirely.
  • To delete the data your instance has already stored, remove the app's device from Home Assistant. In Home Assistant, go to Settings > Devices & services, open the Mobile App integration, and delete the device for that Android/iOS device. This also revokes the access token the app was using.
  • Uninstalling the app removes its data from your device.