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 local and (optionally) remote URL manually. The app detects both and picks the fastest path later. Sign in with your Home Assistant account.

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.

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, orange = connecting, red = offline.

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 →