home-assistant/iOS: building the Home Assistant companion app for Apple platforms

What the Home Assistant iOS app repository actually contains

This is the client, not the server. The README describes the project as "Home Assistant for Apple platforms" and the homepage points at companion.home-assistant.io, a documentation site for the companion apps rather than for Home Assistant itself. If you are searching for what Home Assistant is, this repository will not answer that question: it builds an app that talks to an instance you already run elsewhere.

The code is Swift, licensed Apache-2.0, and lives under Sources/ with a WatchApp/ directory alongside it. There is a HomeAssistant.xcodeproj, a Package.resolved for Swift Package Manager, a fastlane/ directory for CI and deployment, and a Configuration/ directory that holds the xcconfig files. The presence of .claude/, .cursorrules, .windsurfrules and AGENTS.md at the top level tells you the maintainers have made a deliberate decision about AI-assisted contributions; the repository also ships an AI_POLICY.md and a CLA.md.

Who is this for? Two groups. First, contributors who want to fix or extend the app and need a working local build. Second, developers who want to debug the frontend WebView against their own server, which the README treats as a separate, lighter workflow. Everyone else should install the released app from the App Store link in the README and never open Xcode.

How the build is wired: Bundler, Homebrew, SPM and Fastlane

The dependency story is deliberately split. Xcode resolves Swift Package Manager dependencies on its own, so there is no manual SPM step. Ruby tooling, which in practice means Fastlane, is installed through Bundler, and the README offers three ways to get a suitable Ruby: Homebrew's [email protected] formula, rbenv with ruby-build, or mise. You pick one. Running all three would leave you with competing Ruby installations and a confusing bundle path.

The hard requirement is Xcode 26.4 or later, which the README says to download from the App Store. That is a real constraint, not a formality: the project targets current Apple toolchains and an older Xcode will fail before you reach any Home Assistant code.

Code signing is the part that surprises people. The README states that although Debug builds use Automatic provisioning, the app makes heavy use of entitlements that require signing even for simulator builds. That is why a simulator run still asks for a team. The repository expects a file that does not exist in a fresh clone: Configuration/HomeAssistant.overrides.xcconfig, which is git-ignored. You create it yourself, and the configuration then disables features your team is not entitled to, with Critical Alerts named explicitly in the README as an example.

Installing and running the App-Debug scheme

Start by cloning and entering the directory. The README gives these two commands first, before any dependency choice:

git clone https://github.com/home-assistant/iOS.git
cd iOS

Then install Ruby tooling. The README presents three alternatives; this is the Homebrew one, which installs Ruby 3.1 and then runs Bundler from that specific prefix so you do not fight the system Ruby:

brew install [email protected]
$(brew --prefix)/opt/[email protected]/bin/bundle install

If you prefer rbenv, the equivalent pair is `brew install rbenv ruby-build`, then `rbenv install`, then `bundle install`. With mise it is `brew install mise`, then `mise install`, then `bundle install`. The README notes that Swift Package Manager dependencies are resolved automatically by Xcode, so there is nothing else to fetch.

Before opening the project, create the overrides file. The README says it will not exist by default and is ignored by git, and gives these two keys:

DEVELOPMENT_TEAM = YourTeamID
BUNDLE_ID_PREFIX = some.bundle.prefix

Your Team ID is on Apple's developer portal and looks like ABCDEFG123 according to the README. After that, launch HomeAssistant.xcodeproj and run the App-Debug scheme onto a simulator or a device. That is the whole first run: no server configuration, no account, just a signed build of the client.

If your goal is only the frontend, skip all of the above. The README describes downloading a simulator build from the GitHub Actions artifacts, dragging the .app onto a booted simulator, and launching it from the home screen. The simulator maps a click to a tap, click-and-drag to a scroll, and Option to a second touch point. Once it is running you can attach Safari's Web Inspector through the Develop menu and pick the WebView.

Linting, hooks and what the CI actually gates on

The repository runs four linters, and the split between them is worth understanding before you open a pull request. SwiftFormat handles formatting, SwiftLint covers what SwiftFormat does not automate, RuboCop covers Fastlane, and YamlLint covers GitHub Actions files. Inside Xcode, the autocorrectable linters do not rewrite your source; they surface warnings instead. That distinction matters if you assume saving a file cleans it up.

Two Fastlane lanes are documented in the README for local use:

bundle exec fastlane lint
bundle exec fastlane autocorrect

The first checks without fixing, the second fixes. There is also a one-time hook installation, `bundle exec fastlane install_git_hooks`, which runs autocorrect before each commit. If you contribute regularly, that hook is the difference between a clean pull request and a lint failure in CI.

Deployment is also Fastlane, driven from GitHub Actions. The README documents manual paths for Mac and iOS builds that upload to App Store Connect, and mentions that Mac Developer ID builds appear as an artifact on every build of master. For a contributor, the practical implication is that release engineering is not something you do locally; you run lint and autocorrect, and CI handles the rest.

Entitlements, code signing and the limits of a personal build

The single biggest limitation is not in the Swift code. It is in provisioning. The README is explicit that the app uses entitlements requiring code signing even for simulator builds, and that Xcode will generate profiles under your Team ID while the configuration disables features your team does not have. Critical Alerts is the example given. So a build from your own team is not feature-equivalent to the App Store build, and no amount of local configuration changes that. If you are debugging a notification behaviour that depends on an entitlement you cannot provision, you will not reproduce it locally.

The second limitation is toolchain churn. Xcode 26.4 or later is a floor, and the project tracks current Apple platforms. A machine pinned to an older Xcode is the wrong machine for this repository, and there is no documented fallback branch in the README.

The third is scope confusion. People arrive at this repository looking for the Home Assistant server or for the dashboard frontend, and neither lives here. The frontend is a separate repository, linked from the README's testing section, and the server is a different project entirely. If your actual problem is that the app will not connect to your instance, cloning this repository does not help you: the README documents building and debugging, not troubleshooting a connection to a running server.

How this differs from building on Apple HomeKit

The comparison a reader is most likely to make is Home Assistant versus Apple HomeKit, and the repository is a useful place to see the difference concretely. HomeKit is Apple's own framework, and an app built against it inherits Apple's device database, its pairing model and its automation engine. This repository does none of that. It builds a client that talks to a Home Assistant instance you host, and the intelligence, the entity registry and the automations stay on that server.

That has a direct consequence for what you can change. In a HomeKit-based setup, the set of supported accessories is whatever Apple and the manufacturer agree on. Here, the app is one client among several, and the README even points at a separate frontend repository that you can test in a simulator without building the native app at all. The trade is control for responsibility: you get to decide what the server does, and you also have to run it.

There is also a practical difference in contribution surface. HomeKit development means working inside Apple's frameworks and review process. This project takes pull requests, runs its own linters, requires a CLA, and publishes an AI policy. Those are the trappings of an open source project with its own governance, not a platform SDK.

Licence, maintenance and the cost of staying current

The licence is Apache-2.0, per the README and the LICENSE.md file at the top level. Apache-2.0 is permissive and includes an explicit patent grant, which is friendlier to corporate contributors than a bare MIT licence. It is not a copyleft licence, so a fork can be distributed under different terms provided the notice requirements are met. That is a description of the licence text, not legal advice; if you are shipping a modified build commercially, read the file and talk to someone qualified.

Maintenance is visible in the release cadence. The most recent listed release is 2026.8.0 (2805) on 2026-08-26, preceded by 2026.7.3 (2546) on 2026-08-04 and 2026.7.1 (2342) on 2026-07-14. The last push to the default branch was 2026-08-26. The repository is not archived. The versioning tracks the Home Assistant release train rather than following independent semantic versioning, which means upgrades arrive on the server's schedule as well as the app's.

The upgrade cost for a developer is mostly in the toolchain, not the dependency graph. Swift Package Manager dependencies resolve automatically through Xcode, so there is no lockfile to babysit by hand beyond Package.resolved. The recurring expense is keeping Xcode at or above the required version and re-running `bundle install` when the Gemfile changes. For a contributor, that is a few minutes a month. For a team maintaining a private fork, it is a standing commitment tied to Apple's release cycle, and the README offers no guidance on long-term branch maintenance.

Editorial conclusion

Adopt this repository if you are an iOS or Mac developer who wants to run the companion app from source, debug its WebView against your own Home Assistant instance, or contribute to a project that still receives releases (the most recent listed is 2026.8.0 (2805) on 2026-08-26). Do not clone it expecting a self-hosted server: the server is a separate project and this repository only builds the client. Before you start, verify three things: that your Xcode is 26.4 or later, that you have a Team ID you can put in Configuration/HomeAssistant.overrides.xcconfig, and that you are willing to accept that entitlements your team does not hold will be disabled in your build.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes