Collegare una nuova istanza Home Assistant

1. Sul tuo Home Assistant

Serve un'istanza con un URL pubblico HTTPS (es. https://ha-tuodominio.it).

1. Crea un account dedicato, es. claude-connector, con ruolo Administrator — Impostazioni → Persone → Aggiungi persona. Un account dedicato (invece del tuo) permette di revocare l'accesso in futuro senza toccare il tuo utente personale.
2. Accedi con quell'account, apri il tuo profilo (in basso a sinistra), scorri fino a "Token di accesso a lunga durata" e clicca Crea token. Dagli un nome (es. connettore-ha) e copialo subito: Home Assistant lo mostra una sola volta.

2. Aggiungere l'istanza al connettore

Dal repository connettore-ha, esegui lo script di onboarding:

npm run onboard

Ti verranno chiesti:

• id: uno slug breve, es. casa o sede-milano
• nome descrittivo, es. "Casa" o "Sede Milano"
• base_url: l'URL pubblico HTTPS dell'istanza
• verificare SSL?: sì, a meno di certificato self-signed

Lo script aggiunge l'istanza a instances.yaml (nessun segreto scritto su file) e stampa il nome esatto della env var da creare al passo successivo, del tipo HA_TOKEN_<ID>.

3. Collegare il token su Coolify

1. Apri l'app connettore-ha su Coolify → Environment Variables.
2. Aggiungi la variabile con il nome stampato dallo script (es. HA_TOKEN_CASA) e come valore il token generato al passo 1. Il token non deve mai comparire nel repo o in chat.
3. Fai commit + push di instances.yaml aggiornato.
4. Rideploy dell'app (o attendi l'auto-deploy se attivo).

Al riavvio, l'istanza compare in dashboard con il suo stato di health check e le entità in tempo reale.

Note di sicurezza

• Un token = una sola istanza: mai riutilizzarlo su un'altra.
• Per revocare l'accesso a un'istanza: elimina/disabilita l'account claude-connector su quell'istanza, non serve toccare le altre.
• Rotazione consigliata almeno ogni 90 giorni, o subito in caso di sospetto leak.