Setup Guide

Tip

New to Home Assistant? Read Key Concepts first for a quick rundown of the terms used in these docs.

What You Need

• iPhone running iOS 18+
• Apple Watch running watchOS 11+ (paired with your iPhone)
• Home Assistant
• HACS optional, but recommended for the easiest integration install (install guide)

Note

Don’t have Home Assistant yet? Check out home-assistant.io — it’s free and open source.

Setup

Search for Wrist Assistant in the App Store and install it. Open the app on your iPhone — the onboarding covers two things:

1. Connect to Home Assistant. Tap Find my Home Assistant to auto-discover your server on Wi-Fi, or enter your Home Address (same Wi-Fi) and (optionally) Away Address (when you’re not home) manually. The app detects both and picks the fastest path later. Sign in with your Home Assistant account.

   • Reinstalling? If you’ve used Wrist Assistant before, a Previously used card appears offering to refill your prior addresses from your iCloud backup with one tap.
   • Self-signed certificate? If the app can’t trust your server’s HTTPS certificate, it tells you so directly (“HTTPS certificate is not trusted on this device”) — install and trust the certificate on your iPhone, or use the local http:// address instead.

   Note

   A self-signed certificate is about trusting the server’s HTTPS certificate. mTLS (below) is the opposite direction — the server demands that you present a client certificate. They’re unrelated, and you can hit one without the other.

mTLS / client certificate

You only need this if your remote Home Assistant is behind mutual TLS — for example a Cloudflare Access / Cloudflare Tunnel mTLS rule, or an nginx reverse proxy configured to require a client certificate. The server refuses any connection that doesn’t present a certificate it trusts.

How you’ll know. The app surfaces it instead of a generic “can’t reach” error:

• A message like “Server requires a client certificate. Import your .p12 in the Certificate (mTLS) section below.”
• An amber Needs a client certificate (mTLS) badge (and a small needs mTLS badge beside the Remote URL field).
• Browser sign-in failing with a 403 — Safari can’t present a certificate that lives in the app, so the system sign-in dead-ends behind an mTLS rule.

Import your certificate (iPhone only):

1. Go to Settings → Home Assistant, then expand the Certificate (mTLS) section.
2. Tap Import Certificate and pick your .p12 / .pfx file. Can’t get the file onto the phone? Use Paste Base64 instead.
3. If the file is password-protected, the app asks for the export password and finishes the import.

Your normal Home Assistant access token is still required — the certificate is in addition to signing in, not a replacement for it.

Signing in behind mTLS. Once a certificate is imported, the app signs you in through an in-app web view that presents the certificate during the TLS handshake (the normal Safari sign-in can’t). If sign-in still won’t complete, you can:

• Sign in once over your Home Address (same Wi-Fi), which usually isn’t behind the mTLS rule, or
• Paste a Long-Lived Access Token directly (create one in Home Assistant under Profile → Security).

Tip

Import the certificate only on your iPhone — it syncs to your Apple Watch automatically, so there’s nothing to install on the watch.

Caution

The app warns you about 30 days before the certificate expires (and flags it once it has lapsed). When that happens, import the renewed .p12 the same way to replace it.

For security, a client certificate is tied to the device it was imported on and is not included in a backup. After restoring to a new phone (or a fresh install from backup), the app shows the certificate as Didn’t transfer — just re-import the .p12 to reconnect.

2. Install the Wrist Assistant integration. After sign-in, the app checks whether the integration is already installed. If it is not, onboarding offers two paths:

   1. Use HACS. This is the recommended path when HACS is available.
   2. Install manually. This is always available as a fallback.

If you switch into the manual path during onboarding, the back button returns you to the install-choice screen instead of taking you all the way back to server selection or sign-in.

HACS Install

If HACS is available, onboarding presents it as the primary option and can walk you through:

1. Checking for HACS
2. Installing the integration
3. Restarting Home Assistant
4. Waiting for startup
5. Finishing setup automatically

After Home Assistant finishes restarting, the app tries to add and activate the Wrist Assistant integration for you automatically. If Home Assistant shows an extra confirmation form, the app hands off to Safari for that final step.

Manual Install

If you do not have HACS or do not want to use it, choose Install manually in onboarding. The in-app instructions are:

1. Download the Wrist Assistant integration repository
2. Copy custom_components/wrist_assistant into Home Assistant’s config/custom_components/ folder
3. Restart Home Assistant
4. Open Devices & Services
5. Add the Wrist Assistant integration

After that, the app re-checks directly for the Wrist Assistant integration. HACS is not required to finish onboarding.

Once the integration is installed, tap Let’s Go! to finish onboarding. You’ll land on the Pages tab, ready to build your first layout.

Tip

If the watch app doesn’t show up automatically, open the Watch app on your iPhone, find Wrist Assistant, and tap Install.

Note

A brand-new watch first shows a Set Up on iPhone screen (“Open the Wrist Assistant app on your iPhone to connect and create pages”). It clears itself once you open the iPhone app and keep it open for a moment while your pages sync across — there’s no need to force-quit the watch app. The first time the app reaches Home Assistant over a local address, iOS asks for Local Network permission; that address may briefly show a red ✕ and turns green on its own once you tap Allow.

Setup Check

Setup Check verifies your whole setup end-to-end on a single page and offers a one-tap fix for anything that’s broken. It’s organized into per-device sections, each with live spinners and a green check when it’s healthy:

Home Assistant — server reachable, long-lived token valid, live updates connected, HACS installed (advisory), the Wrist Assistant integration installed, and the integration up to date.

iPhone — iPhone registered for notifications, and notification permission (advisory).

Apple Watch — watch registered and watch live updates working.

Device & app — advisory checks for subtler problems: Watch app matches iPhone, watch configuration sync, widget credentials, and device clock drift.

Manual tests — run only when you tap them, since each reaches out to Home Assistant: send a test notification, send a snapshot notification, check that camera streaming works (when a camera is configured), and audit that every entity in your layout still exists.

Each failing step shows a fix button — Sign in again, Reconnect, Install Integration, Update Integration, Open hacs.xyz, or Try Again — so you can resolve issues without leaving the page.

Setup Check runs automatically after a major app update (or whenever a required step is failing). You can defer it with I’ll do this later — a red reminder bar stays until you finish — and you can re-run it any time from Settings → Home Assistant → Run Setup Check.

Keeping the watch app up to date

The Watch app matches iPhone check is advisory — it never blocks the rest of Setup Check. When the watch is running an older version than the iPhone, it settles into a calm Watch app update pending state: a steady down-arrow icon and a red version badge on the Apple Watch section header, rather than a stuck-looking spinner.

This is normal and self-healing. After you update Wrist Assistant from the App Store, watchOS reinstalls the embedded watch app on its own schedule — often a few hours later — and the app can’t trigger that install itself. The check just shows you which device is behind in the meantime.

If you’d rather not wait, there are two manual levers (tap Update it now on that row to see them):

• Put your Apple Watch on its charger, near your iPhone, both on Wi-Fi. watchOS installs queued updates while the watch charges — this is what usually triggers it.
• Or force it now: open the Watch app on your iPhone, find Wrist Assistant, and toggle Show App on Apple Watch off, then back on. That reinstalls the current version right away.

Note

The app no longer checks the App Store for its own version — that check lagged the storefront by hours and could show wrong “update available” prompts. To see what changed in a release, use the Changelog link in Settings.

How the Watch Connects

The watch finds the fastest path to Home Assistant automatically:

• Wi-Fi — Direct connection, near-instant response
• iPhone relay — Routes through your phone via Bluetooth when Wi-Fi isn’t available
• Offline — Shows last known states until a connection comes back

The connection dot (to the right of the clock on your watch): green = connected locally, orange = connected remotely, yellow = connecting or degraded, red = offline or error.

What Watches Are Supported?

Any Apple Watch running watchOS 11+. Some features need specific hardware:

• Hand gestures (double-pinch) — Series 9, Ultra 2, or newer
• Action Button — Ultra models only
• Control Center widgets — watchOS 26 and later

Next Up

Build your first page →

Something not working? Troubleshooting →