Problem statement
HACS (Home Assistant Community Store) is a valuable resource for Home Assistant users, but its current installation process creates unnecessary friction that prevents less technical users from accessing community integrations and add-ons. The installation requires CLI access, manual wget commands, multiple restarts, and cache clearing — barriers that exclude users who are comfortable with UI-based workflows but not command-line operations.
Additionally, the GitHub authentication flow and acknowledgment requirements lack integration with HA's native UI patterns, creating a disjointed experience.
Community signals
Installation Friction Evidence:
Technical Barriers:
- Current installation requires 7 distinct steps including CLI commands, manual restarts, and cache clearing
- Multiple community forum threads document installation failures and confusion, particularly for HA OS users who struggle with CLI access requirements:
- Users frequently encounter technical errors during wget script execution, network resolution failures, and permission issues across different installation types:
- Docker users face additional complexity navigating container file systems and volume mappings (https://www.wundertech.net/how-to-install-hacs-on-home-assistant/)
Beginner Accessibility Gap:
- Official HACS documentation explicitly states: "If you don't know what type of Home Assistant installation you are running, you should not use HACS (or any other custom integration)" — this creates a significant barrier for non-technical users who would otherwise benefit from community integrations (https://www.hacs.xyz/docs/use/download/download/)
- Home Assistant's own blog post acknowledges HACS as "not for beginners" despite its value, stating: "If you are a beginner or prioritize stability above all else, HACS might not be for you" and describing it as an "advanced tool" that requires caution (https://www.home-assistant.io/blog/2024/08/21/hacs-the-best-way-to-share-community-made-projects/)
- Third-party tutorial sites consistently emphasize that HACS installation is "a little bit convoluted" and requires enabling Advanced Mode + SSH access — steps that intimidate less technical users:
Community Confusion & Support Burden:
- Recurring confusion between HACS (integration) and the "Get HACS" add-on used during installation
- Reddit users report spending hours searching multiple pages trying to understand installation steps, with one user noting they "Finally several pages in google later" found the correct documentation (https://www.reddit.com/r/homeassistant/comments/1ghkeeb/how_can_you_install_hacs/)
- GitHub issue tracker shows persistent activation failures, where users successfully run the installation script but HACS fails to appear in their integrations list:
- Multiple users report needing to restart Home Assistant multiple times and clear caches manually:
GitHub Authentication Friction:
- GitHub device authorization flow requires users to leave HA, manually copy 8-digit codes, navigate external authorization pages, and return — creating a disjointed experience (visible in installation screenshots)
- Users frequently get stuck on the GitHub OAuth step, with some reporting the authorization completing but HACS still failing to activate:
Demand Signal:
- Despite installation complexity, HACS remains one of the most widely adopted community tools for Home Assistant
- Community consistently recommends HACS as essential for power users: HowToGeek article titled "All Home Assistant Users Should Install This Custom Integration" (https://www.howtogeek.com/all-home-assistant-users-should-install-this-custom-integration/)
- The existence of numerous third-party installation tutorials and YouTube guides indicates organic demand for simplified access
Scope & Boundaries
In scope
- Remove CLI installation requirement — enable HACS installation entirely through HA's UI
- Gate HACS behind Home Assistant Labs to allow controlled rollout and potential rollback
- Add HACS as a Labs feature card following existing Labs UI patterns
- Integrate HACS's four required acknowledgments into HA's native UI patterns
- Streamline the installation flow to eliminate manual restarts and cache clearing steps
- Provide clear explanation of GitHub account requirement (OAuth authentication + rate limiting) within the flow
- Investigate whether HA's existing GitHub authentication mechanism (used for App Store custom repositories) can eliminate the need for individual user GitHub accounts
Not in scope
- HACS UI redesign (separate opportunity planned)
- GA transition to App Store (future opportunity after Labs validation)
- Changes to how HACS functions post-installation
- Changes to HACS content curation or quality standards
- Individual user GitHub authentication requirement (pending investigation — if HA's backend auth is sufficient, this becomes unnecessary)
Foreseen solution
Phase 1: Labs Release
Add HACS as a new Labs feature card in Settings > System > Labs, following the existing pattern (similar to "Device database", "Purpose-specific triggers and conditions", etc.).
HACS Labs Card:
Title: "HACS (Home Assistant Community Store)"
Category: Integration / Community
Description: Brief explanation of HACS and what it provides
Enable/Disable toggle: Triggers installation flow when enabled
Installation Flow (when user enables HACS in Labs):
- Acknowledgment Screen: Present the four existing HACS acknowledgments in HA's native dialog pattern:
- "I know how to access Home Assistant logs"
- "I know that there are no add-ons in HACS"
- "I know that everything inside HACS including HACS itself is custom and untested by Home Assistant"
- "I know that if I get issues with Home Assistant I should disable all my custom_components"
Add contextual explanation: "HACS provides community-maintained integrations that don't meet Home Assistant's core stability and security requirements."
Note: GitHub account explanation included only if user authentication proves necessary after investigation.
- One-Click Installation: Backend handles the current wget/bash workflow automatically — no CLI access required
- GitHub Authentication (if required after investigation): Use existing HA device authorization pattern:
- Display device code
- Link to GitHub authorization page
- Wait for user to complete OAuth flow
- Automatic device activation upon completion
Alternative: If HA's backend GitHub authentication (used for App Store custom repositories) is sufficient, skip user authentication entirely.
- Automated Setup: Handle restarts and cache clearing programmatically with progress indicators
Post-Install: HACS appears in integrations list with repositories accessible
Phase 2: GA Transition (Future - Out of Scope for This Opportunity)
Once Labs validation is complete and HACS installation is deemed stable, move installation to App Store UI (separate opportunity). This initial opportunity focuses solely on the Labs implementation
Risks & open questions
PRIORITY INVESTIGATION:
- Can we eliminate individual user GitHub authentication entirely? The App Store already allows users to add custom GitHub repositories (via "Repositories" → "+ Add") without requiring user GitHub accounts. This strongly suggests HA has backend GitHub authentication. Key questions:
- Does HA's backend already authenticate to GitHub for App Store custom repository access?
- Can HACS leverage the same mechanism?
- What's the actual purpose of HACS's current GitHub user requirement — is it technical necessity or legacy from pre-OHF days?
- Rate limiting: Does adding HACS's repository list create problems, or is it already handled by HA's backend?
- If backend auth is sufficient, this could eliminate significant user friction and simplify the entire installation flow
Other Open Questions:
- Restart/cache handling: Can restarts be automated gracefully, or do users still need to trigger manually? What's the UX during automated restart?
- Labs rollback: If HACS installation causes issues, what's the rollback process? Can users uninstall cleanly from Labs?
- Acknowledgment refinement: The current four warnings are functional but verbose. Should we explore more elegant presentation while retaining the same information?
- Support burden: Making HACS more accessible may increase support requests about community add-ons — how do we set expectations that these aren't officially supported?
- Labs card description: What's the optimal brief description for the HACS Labs card that clearly communicates value and risk?
Appetite
Medium / 1 cycle (2 months)
This involves UI work for the Labs feature card, acknowledgment screen redesign, backend automation of the installation script, investigation and potential implementation of backend GitHub authentication (vs. user OAuth), and testing across different HA installation types (OS, Container, Core). Should be achievable in one cycle with focused effort.
If the GitHub authentication investigation reveals that backend auth can eliminate user authentication entirely, this could actually reduce scope and make the opportunity more achievable within the cycle.
Execution issues
To be created during implementation
Decision log
Problem statement
HACS (Home Assistant Community Store) is a valuable resource for Home Assistant users, but its current installation process creates unnecessary friction that prevents less technical users from accessing community integrations and add-ons. The installation requires CLI access, manual wget commands, multiple restarts, and cache clearing — barriers that exclude users who are comfortable with UI-based workflows but not command-line operations.
Additionally, the GitHub authentication flow and acknowledgment requirements lack integration with HA's native UI patterns, creating a disjointed experience.
Community signals
Installation Friction Evidence:
Technical Barriers:
Beginner Accessibility Gap:
Community Confusion & Support Burden:
GitHub Authentication Friction:
Demand Signal:
Scope & Boundaries
In scope
Not in scope
Foreseen solution
Phase 1: Labs Release
Add HACS as a new Labs feature card in Settings > System > Labs, following the existing pattern (similar to "Device database", "Purpose-specific triggers and conditions", etc.).
HACS Labs Card:
Title: "HACS (Home Assistant Community Store)"
Category: Integration / Community
Description: Brief explanation of HACS and what it provides
Enable/Disable toggle: Triggers installation flow when enabled
Installation Flow (when user enables HACS in Labs):
Add contextual explanation: "HACS provides community-maintained integrations that don't meet Home Assistant's core stability and security requirements."
Note: GitHub account explanation included only if user authentication proves necessary after investigation.
Alternative: If HA's backend GitHub authentication (used for App Store custom repositories) is sufficient, skip user authentication entirely.
Post-Install: HACS appears in integrations list with repositories accessible
Phase 2: GA Transition (Future - Out of Scope for This Opportunity)
Once Labs validation is complete and HACS installation is deemed stable, move installation to App Store UI (separate opportunity). This initial opportunity focuses solely on the Labs implementation
Risks & open questions
PRIORITY INVESTIGATION:
Other Open Questions:
Appetite
Medium / 1 cycle (2 months)
This involves UI work for the Labs feature card, acknowledgment screen redesign, backend automation of the installation script, investigation and potential implementation of backend GitHub authentication (vs. user OAuth), and testing across different HA installation types (OS, Container, Core). Should be achievable in one cycle with focused effort.
If the GitHub authentication investigation reveals that backend auth can eliminate user authentication entirely, this could actually reduce scope and make the opportunity more achievable within the cycle.
Execution issues
To be created during implementation
Decision log