Как установить HACS

Введение

Home Assistant — мощная платформа для умного дома. Но возможности базовой установки ограничены. Чтобы добавить новые интеграции, пользовательские панели, карточки интерфейса и полезные утилиты, удобно использовать HACS (Home Assistant Community Store). Это каталог дополнений от сообщества, который открывает доступ к тысячам готовых решений.

Что такое HACS и зачем он нужен

HACS — это менеджер репозиториев, который позволяет:

• быстро находить и устанавливать пользовательские интеграции
• добавлять кастомные карточки для Lovelace UI
• управлять обновлениями сторонних дополнений
• расширять функциональность без ручного копирования файлов

Проект развивается сообществом на GitHub: https://github.com/hacs.
В текущий момент доступно более 1500 интеграций, их список: https://github.com/hacs/default/blob/master/integration.

Предварительные требования

Перед установкой убедитесь, что:

• Есть доступ в интернету
• У вас установлена актуальная версия Home Assistant (рекомендуется последняя стабильная)
• Вы используете аккаунт администратора и имеете доступ к конфигурации (директория config)

Установка HACS через SSH

Этот способ установки основан на запуске официального установочного bash-скрипта HACS. Для этого требуется доступ к командной строке сервера Home Assistant, обычно через SSH.

1. Убедитесь, что находитесь в каталоге конфигурации Home Assistant (обычно /config)
2. Выполните команду:

wget -O - https://get.hacs.xyz | bash -

4. Перезапустите Home Assistant

Для сверки: после запуска установочного скрипта в терминале финальные строки при успешной установке выглядят так:

INFO: Creating HACS directory...
INFO: Unpacking HACS...

INFO: Verifying versions
INFO: Current version is 2025.9.4, minimum version is 2024.4.1

INFO: Removing HACS zip file...
INFO: Installation complete.

INFO: Remember to restart Home Assistant before you configure it
➜  config

Если вы управляете несколькими инстансами Home Assistant или предпочитаете декларативный подход, установку HACS можно автоматизировать через Ansible. Подробные примеры приведены в приложении «Установка HACS через Ansible». Данные примеры не содержат последующей конфигурации — например, авторизации HACS через GitHub и ввода кода подтверждения. Эти шаги необходимо выполнить вручную, как описано дальше. Такой подход особенно удобен в CI/CD сценариях и при поддержке нескольких серверов: код в Git остаётся источником правды, а установка становится повторяемой и предсказуемой.

Установка HACS вручную

Этот способ установки предполагает ручное скачивание и размещение файлов HACS в каталоге конфигурации Home Assistant без использования установочных скриптов.

1. Скачайте архив с последней стабильной версией (Source code / ZIP) с https://github.com/hacs/integration/releases и распакуйте его локально
2. В каталоге конфигурации (обычно /config) Home Assistant откройте (или создайте) папку: /config/custom_components/hacs
3. Скопируйте содержимое распакованного архива в custom_components/hacs
4. Перезапустите Home Assistant

Установка HACS через Дополнения

Если ваш тип установки Home Assistant поддерживает работу с Дополнениями (add-on), вы можете установить HACS с помощью официального дополнения без ручного копирования файлов и выполнения команд в терминале.

1. Добавьте репозиторий дополнения HACS, перейдя по официальной ссылке:
   https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https://github.com/hacs/addons
2. Подтвердите открытие ссылки в Home Assistant и добавление репозитория
3. В списке Дополнений Home Assistant откройте Get HACS add-on, установите и запустите его
4. Перейдите в логи дополнения и следуйте инструкциям, которые будут выведены там

После завершения работы дополнения установка HACS считается выполненной.

Какой способ установки выбрать

Home Assistant может быть установлен несколькими способами, и от типа установки зависит, какой вариант установки HACS будет доступен. В целом Home Assistant устанавливается в одном из четырёх режимов. Подробнее о различиях между ними — в статье Как установить Home Assistant: четыре способа, их плюсы и минусы.

Ниже приведены рекомендации по выбору способа установки HACS для каждого типа установки Home Assistant.

Установка для Home Assistant OS

Home Assistant OS — самый распространённый вариант установки, при котором система полностью управляется через Supervisor.

Для этого типа установки доступны следующие способы установки HACS:

• установка с помощью официального bash-скрипта
• установка через Дополнения
• ручная установка

Рекомендуемый вариант — установка с помощью bash-скрипта. Этот способ наиболее прозрачный, не зависит от состояния Supervisor и позволяет полностью контролировать процесс установки. Подключение к системе и работа с терминалом (включая SSH-доступ) описаны в статье Настраиваем SSH-доступ к Home Assistant.

Установка для Home Assistant Supervised (Debian)

Home Assistant Supervised устанавливается на Debian и использует Supervisor, но при этом система остаётся полноценным Linux-хостом.

Для этого типа установки доступны:

• установка с помощью официального bash-скрипта
• установка через Дополнения
• ручная установка

На практике чаще всего используется установка с помощью bash-скрипта, так как она не привязана к состоянию Supervisor и проще в отладке. Установка через Дополнения и ручная установка также возможны, но используются реже.

Установка для Home Assistant Container (Docker)

Home Assistant Container запускается в Docker-контейнере и не использует Supervisor.

Для этого типа установки доступны:

• установка с помощью bash-скрипта (при наличии bash в окружении)
• ручная установка

Важно учитывать, что bash-скрипт может быть запущен только в окружениях, где доступна командная строка bash. В случае использования Docker на Windows запуск bash-скрипта напрямую невозможен.

На практике в Docker-установках чаще всего используется маппинг каталога config контейнера на каталог хостовой системы. Это позволяет запускать bash-скрипт (на Linux-хостах) или распаковывать файлы HACS непосредственно на хосте в каталог, который примонтирован в контейнер как config. Подробнее о настройке Home Assistant Container и работе с Docker — в статье Установка Home Assistant в Docker: гибкость без Supervisor.

Установка для Home Assistant Core (Python)

Home Assistant Core устанавливается как Python-приложение и предполагает ручное управление окружением.

Для этого типа установки доступны:

• установка с помощью bash-скрипта (при наличии bash в окружении)
• ручная установка

На Linux-системах обычно используется bash-скрипт или ручная установка. При использовании Home Assistant Core на Windows bash-скрипт, как правило, недоступен, поэтому применяется ручная установка с копированием файлов в каталог конфигурации.

Первоначальная настройка HACS (через GUI)

1. Откройте Настройки → Интеграции → Добавить интеграцию и найдите HACS
2. Отметьте чекбоксы согласия (о доступе к логам, отсутствии add-ons в HACS, кастомном характере компонентов и необходимости отключать custom_components при проблемах) и нажмите Подтвердить
3. Пройдите авторизацию GitHub по Device Flow: на экране появится код и ссылка. Перейдите на github.com/login/device, вставьте код и подтвердите доступ. Вернитесь в Home Assistant и дождитесь завершения
4. После успешной активации в левом меню появится пункт HACS — откройте его: отобразится каталог интеграций и карточек

Где хранится токен GitHub и зачем он нужен

Зачем нужен токен. HACS использует GitHub API для поиска репозиториев, чтения релизов и скачивания архивов. Авторизация токеном поднимает лимиты GitHub API, делает обновления стабильнее и (при желании) даёт доступ к приватным репозиториям.

Где хранится. На актуальных версиях Home Assistant токен HACS хранится в JSON‑файле .storage/core.config_entries (относительно каталога config; на HAOS это обычно /config/.storage/core.config_entries). Внутри файла найдите запись с "domain": "hacs" и поле "data.token" — это и есть ваш токен.

Пример токена:

➜  config cat .storage/core.config_entries| grep hacs
      {"created_at":"2025-09-25T08:04:43.992573+00:00","data":{"token":"gho_*************************************"},"disabled_by":null,"discovery_keys":{},"domain":"hacs","entry_id":"01K5ZYEEARV001YKV6SD96PVH0","minor_version":1,"modified_at":"2025-09-25T08:04:43.992574+00:00","options":{"experimental":true},"pref_disable_new_entities":false,"pref_disable_polling":false,"source":"user","subentries":[],"title":"","unique_id":null,"version":1}

Срок действия токена. Это OAuth‑токен GitHub без фиксированного срока жизни; он действует, пока вы не отзовёте доступ приложения HACS в GitHub (Settings → Applications → Authorized OAuth Apps) или пока GitHub не отзовёт его автоматически (например, при годе неактивности или в случае утечки).

Использование HACS

• Установка компонентов: откройте HACS и выберите нужный плагин или интеграцию
• Обновления: HACS уведомляет о новых версиях - достаточно нажать "Update"
• Управление: удаление или отключение компонентов происходит в пару кликов

Заключение

HACS делает Home Assistant действительно гибкой платформой. С его помощью можно легко добавить новые возможности, кастомизировать интерфейс и держать все плагины в актуальном состоянии.

Приложение: установка HACS через Ansible

Ниже приведены фрагменты роли Ansible для установки HACS. Чтобы они заработали, необходимо определить переменные окружения, в частности:

• hass__user — системный пользователь, под которым работает Home Assistant
• hacs__release_path — каталог, куда устанавливается Home Assistant
• hass__config_path — путь к конфигурации Home Assistant (например, /config)
• при необходимости: hass__hacs_installer_url, hass__hacs_installer_path

Оба подхода ставят HACS, но отличаются способом реализации. Первый способ проще и быстрее, но менее детерминированный и часто вызывает нарекания линтеров из‑за использования shell и пайпов. Второй способ считается более «правильным» с точки зрения Ansible: он чище для линтера, позволяет явно контролировать условия установки и исключает повторные действия.

Первый способ (shell с пайпом)

- name: Install HACS
  become: true
  become_user: "{{ hacs__user }}"
  ansible.builtin.shell: "wget -O - https://get.hacs.xyz | bash -"
  environment:
    PATH: "{{ hacs__release_path }}:{{ ansible_env.PATH }}"
  args:
    executable: /bin/bash
    chdir: "{{ hacs__release_path }}"
  with_items:
    - wget -O - https://get.hacs.xyz | bash -
  notify:
    - Restart hass
  register: hacs__result
  changed_when: "'Remember to restart' in (hacs__result.stdout | default(''))"

Второй способ (stat + get_url + command)

- name: Check HACS installation
  ansible.builtin.stat:
    path: "{{ hass__config_path }}/custom_components/hacs/manifest.json"
  register: hass__hacs_manifest

- name: Download HACS installer script
  ansible.builtin.get_url:
    url: "{{ hass__hacs_installer_url | default('https://get.hacs.xyz') }}"
    dest: "{{ hass__hacs_installer_path | default('/tmp/hacs-install.sh') }}"
    mode: '0755'
  when: not hass__hacs_manifest.stat.exists

- name: Run HACS installer
  become: true
  become_user: "{{ hass__user }}"
  ansible.builtin.command: /bin/bash "{{ hass__hacs_installer_path | default('/tmp/hacs-install.sh') }}"
  args:
    chdir: "{{ hass__config_path }}"
    creates: "{{ hass__config_path }}/custom_components/hacs/manifest.json"
  environment:
    PATH: "{{ hass__release_path }}:{{ ansible_env.PATH }}"
  register: hass__hacs_install
  when: not hass__hacs_manifest.stat.exists

- name: Remove HACS installer script
  ansible.builtin.file:
    path: "{{ hass__hacs_installer_path | default('/tmp/hacs-install.sh') }}"
    state: absent
  when: hass__hacs_install is defined

Приложение: полезные ссылки

• Официальный сайт HACS — https://www.hacs.xyz/
• GitHub HACS — https://github.com/hacs