O que você vai precisar
Passo a passo
1. Faça backup completo antes do HACS
Abra Configurações > Sistema > Backups e crie um backup completo. HACS instala código comunitário dentro do Home Assistant. A maioria funciona bem; a minoria quebrada é justamente a que faz você agradecer por ter backup.
2. Escolha o método de instalação
O método mais confortável em Home Assistant OS é usar o Get HACS, quando disponível via repositório oficial do projeto. Usuários avançados podem instalar pelo Terminal com o script oficial. Evite tutorial antigo copiado de fórum sem data.
Dica: Use sempre a documentação atual do HACS. Mudança de método de instalação é comum em projeto comunitário.3. Instale o Get HACS ou rode o script oficial
Se usar Get HACS, adicione o repositório indicado pela documentação do HACS, instale o app, inicie e acompanhe os logs. Se usar Terminal, execute apenas o comando oficial do site do HACS. Nada de colar script desconhecido porque alguém prometeu facilidade.
4. Reinicie o Home Assistant
Depois que os arquivos forem baixados, reinicie o Home Assistant. Sem reinício, a integração HACS pode não aparecer em Dispositivos e Serviços. Esse é um detalhe bobo que derruba muita primeira instalação.
5. Adicione a integração HACS
Vá em Configurações > Dispositivos e Serviços > Adicionar integração e procure HACS. Aceite os termos, leia os avisos e siga para autorização no GitHub.
6. Autorize o HACS no GitHub
O HACS mostra um código de dispositivo. Abra o endereço indicado, entre na sua conta GitHub e autorize. Essa etapa permite ao HACS consultar repositórios, versões e downloads sem transformar o Home Assistant em navegador improvisado.
Dica: Não use conta GitHub de terceiros. Em projeto profissional, crie conta ou organização do cliente.7. Espere a primeira sincronização
Na primeira abertura, o HACS sincroniza repositórios e categorias. Integrações, Frontend, Templates e temas podem demorar alguns minutos para aparecer completos. Não comece a instalar tudo enquanto a lista ainda carrega.
8. Instale um item simples primeiro
Escolha algo de baixo risco, como um card visual bem mantido. Instale, reinicie se necessário, teste e só então avance para integrações customizadas. HACS não é corrida de carrinho no supermercado.
9. Avalie manutenção antes de instalar
Abra o repositório do item. Veja data do último commit, issues abertas, compatibilidade com a versão atual do Home Assistant e quantidade de usuários. Repositório abandonado há 2 anos não deveria entrar em instalação crítica.
10. Separe visual de infraestrutura
Cards de dashboard podem quebrar visual. Integrações customizadas podem quebrar lógica da casa. Trate as duas coisas de forma diferente. Painel feio incomoda; portão que não responde preocupa.
11. Atualize HACS com janela de manutenção
Atualize itens do HACS quando você puder testar depois. Leia changelog de integração crítica. O botão atualizar é fácil; desfazer no escuro é outra conversa.
12. Remova o que não usa
HACS bom é HACS magro. Remova temas, cards e integrações que ficaram de teste. Código comunitário parado dentro da casa é dívida técnica acumulando poeira.
HACS parece uma loja de aplicativos para Home Assistant. Não é uma loja no sentido confortável da palavra. A segunda frase quebra o encanto porque precisa: HACS é uma porta para código comunitário, e porta boa também precisa de fechadura.
Eu gosto do HACS. Uso. Recomendo em projetos que pedem dashboards melhores, integrações que ainda não chegaram ao núcleo oficial e recursos que a comunidade resolveu antes da plataforma. Mas não trato como brinquedo. O mesmo repositório que entrega um card lindo para a parede da sala pode estar abandonado, sem teste na versão atual, dependendo de API instável ou mantido por uma pessoa que cansou do projeto.
“Backup antes, sempre”#
A primeira regra do HACS é anterior ao HACS. Faça backup completo. Não backup parcial, não captura de tela, não “eu lembro como estava”. Backup. O HACS mexe em arquivos custom_components, recursos de frontend e integrações que carregam junto com o Home Assistant. Quando algo entra mal, a interface pode ficar estranha, logs podem encher e integrações podem falhar.
Isso não significa que HACS seja perigoso por natureza. Significa que ele amplia seu poder de instalar coisas fora do fluxo oficial. Poder sem reversão é teimosia.
“HACS não é oficial”#
A documentação do HACS é clara ao apresentar o projeto como uma interface para gerenciar custom elements no Home Assistant. Custom element não é a mesma coisa que integração revisada e distribuída pelo núcleo do Home Assistant. Essa distinção muda o nível de confiança.
Itens oficiais passam por outro processo, com revisão, padrões e manutenção mais próxima do projeto central. Itens HACS dependem do mantenedor. Alguns são excelentes, melhores que muita integração comercial. Outros são experimentos bonitos com duas issues abertas e um README otimista demais.
Você instalaria um relé sem saber a corrente máxima? Então por que instalaria uma integração que controla relé sem olhar manutenção?
“Comece pelo que pode quebrar sem estrago”#
A primeira instalação depois do HACS deveria ser um card visual. Algo como um cartão de dashboard popular, tema ou componente de frontend que, se der errado, não apaga luz nem abre portão. Isso permite validar o fluxo: instalar, reiniciar, adicionar recurso, testar, atualizar e remover.
Integração customizada vem depois. Principalmente se ela mexe com ar-condicionado, fechadura, alarme, energia, portão ou presença. Quando o assunto encosta em segurança física, o critério sobe. Eu não deixaria uma integração abandonada controlar acesso externo da casa, mesmo que funcione no teste de bancada.
“GitHub é parte do processo”#
HACS usa GitHub para consultar repositórios e versões. A autorização por código de dispositivo assusta menos do que parece: você entra na conta GitHub, digita o código e permite que o HACS trabalhe. Em instalação pessoal, conta gratuita resolve. Em instalação de cliente, use conta do cliente ou organização do projeto.
O erro é autorizar com conta pessoal do integrador e nunca documentar. Depois, quando o cliente precisa atualizar ou transferir manutenção, a casa depende de credencial que nem pertence a ela. Isso é gambiarra administrativa, e gambiarra administrativa quebra tanto quanto fio mal apertado.
“Repositório vivo deixa rastros”#
Antes de instalar um item pelo HACS, abra o repositório. Veja quando foi o último commit. Leia as últimas issues. Confira se há release recente, se o README cita versões atuais do Home Assistant e se outros usuários reportam erro parecido. Projeto vivo não é projeto sem problema; é projeto onde os problemas recebem resposta.
Um componente com 5 mil estrelas, atualização recente e issues respondidas merece mais confiança que um fork obscuro com três commits. Número não garante qualidade, mas silêncio prolongado é sinal ruim. Casa inteligente tem vida longa. Repositório morto vira herança maldita.
“Atualização também quebra”#
HACS facilita atualizar. Esse é o benefício e o risco. Um clique traz correção, recurso novo e, ocasionalmente, incompatibilidade. Leia changelog quando a integração controla algo relevante. Atualize card visual sem tanta cerimônia; atualize integração de alarme com janela de teste.
A melhor prática é simples: backup, atualizar um grupo pequeno, reiniciar quando pedido, testar automações críticas e só então seguir. Quem atualiza 18 componentes do HACS junto com uma versão principal do Home Assistant perdeu o direito de reclamar que não sabe o que quebrou.
“Dashboard bonito não compensa base fraca”#
HACS ficou famoso pelos cards. Mushroom, Bubble Card, mini-graph-card, layout-card, card-mod e dezenas de outros transformam o dashboard. Eles ajudam muito. Um painel bom reduz atrito para quem mora na casa. Mas visual não deveria vir antes de Zigbee estável, backup, nomes de entidades e automações confiáveis.
A ordem saudável é base, depois estética. Primeiro rede, segurança e backup. Depois card redondinho no tablet da sala. Inverter isso cria a casa mais bonita do bairro e a mais chata de manter.
“Integração customizada pede plano de saída”#
Antes de depender de uma integração HACS, pergunte como você sairia dela. Existe integração oficial alternativa? O dispositivo aceita MQTT? O fabricante tem API local? Se o mantenedor sumir, a casa perde função crítica ou apenas um painel?
Essa pergunta parece pessimista. Na prática, é engenharia. Software comunitário muda, APIs fecham, fabricantes alteram autenticação, bibliotecas deixam de funcionar. Quando você planeja saída, a casa não fica refém de entusiasmo.
“HACS bom é HACS documentado”#
Depois de instalar, documente o que entrou. Nome do repositório, função, motivo da instalação, dependência e impacto se parar. Em uma casa com 3 itens HACS, dá para lembrar. Em uma com 25, ninguém lembra. Nem você.
Essa documentação cabe em uma nota simples. Ela ajuda em migração de hardware, restauração de backup e suporte profissional. Também revela excesso: se você não consegue explicar por que instalou um componente, talvez ele devesse sair.
“Quando não instalar HACS”#
Não instale HACS só porque todo tutorial mostra. Se o Home Assistant já faz o que você precisa com integrações oficiais e dashboard nativo, espere. Cada componente customizado aumenta superfície de manutenção. Menos código é menos coisa para quebrar.
Também não instale em casa de cliente sem explicar o que é comunitário e o que é oficial. Transparência evita cobrança injusta depois. O cliente precisa saber que parte do sistema depende de mantenedor externo à plataforma principal.
HACS é excelente quando resolve um problema real. É péssimo quando vira catálogo de ansiedade.
Instale HACS como quem coloca uma nova chave no quadro de energia: sabendo o que ela alimenta e como desligar se der problema. Usado com critério, ele deixa o Home Assistant mais completo. Usado no impulso, transforma personalização em dívida técnica.