Come installare Home Assistant su OrbStack (Mac) con Docker Compose

Se sviluppi automazioni, testi configurazioni o lavori su custom card per Home Assistant, prima o poi ti serve un ambiente di test che sia veloce da avviare, leggero e che non rischi di toccare il tuo sistema di produzione. Su Mac, la soluzione migliore che ho trovato si chiama OrbStack.

In questo articolo ti mostro come installare Home Assistant su OrbStack usando Docker Compose, come strutturare le cartelle, e come aggiungere HACS per avere accesso alle integrazioni e custom card della community. Il video su YouTube segue esattamente questi stessi step.

Cos’e OrbStack e perche usarlo

OrbStack e un’applicazione Mac che sostituisce Docker Desktop — fa girare container Docker e macchine virtuali Linux in modo nativo, con un impatto sulle risorse del sistema praticamente nullo. Meno di 0,1% di CPU in background su Apple Silicon, meno di 10 MB di footprint su disco.

Rispetto a Docker Desktop e piu veloce, si avvia prima e gestisce meglio il networking su Mac. Se sei gia su Docker Desktop, la migrazione e trasparente: OrbStack riconosce container, volumi e immagini esistenti.

OrbStack e gratuito per uso personale. Per uso commerciale richiede una licenza a pagamento — i dettagli sono sulla pagina prezzi di OrbStack.

Cosa ottieni (e cosa NON ottieni) con questa installazione

Prima di iniziare, e importante essere chiari su un aspetto tecnico: questa guida installa Home Assistant Container, non Home Assistant OS.

La differenza pratica: Home Assistant Container include tutto quello che ti serve per sviluppo e test — integrazioni, HACS, automazioni, dashboard Lovelace e accesso completo al file system di configurazione. Quello che non troverai sono gli Add-on del Supervisor (Mosquitto add-on, ESPHome add-on, ecc.).

Per un ambiente di test, sviluppo e prova di configurazioni e piu che sufficiente. Per chi vuole un sistema di produzione completo con Add-on, la strada rimane Home Assistant OS su Raspberry Pi o hardware dedicato.

Step 1 — Scarica e installa OrbStack

Vai su orbstack.dev e scarica l’app. E un normale .dmg, lo installi come qualsiasi applicazione Mac.

Al primo avvio OrbStack installa automaticamente i comandi docker, docker compose e docker buildx nel PATH di sistema. Se hai gia Docker Desktop installato, OrbStack lo rileva e ti offre di migrare i dati esistenti — puoi farlo o saltare, a seconda del tuo setup.

Verifica che tutto funzioni aprendo il Terminale:

docker --version
docker compose version

Se vedi le versioni, sei pronto.

Step 2 — Crea la struttura delle cartelle

Organizziamo il progetto in modo pulito. Apri il Terminale e crea la cartella principale con la sottocartella di configurazione:

mkdir -p ~/homeassistant/config
cd ~/homeassistant

La cartella config conterra tutti i file di Home Assistant — automazioni, integrazioni, database, tutto. E il volume che mappiamo nel container.

Step 3 — Crea il file docker-compose.yml

Nella cartella ~/homeassistant crea il file docker-compose.yml con questo contenuto:

services:
homeassistant:
  container_name: homeassistant
  image: ghcr.io/home-assistant/home-assistant:stable
  volumes:
    - ./config:/config
    - /etc/localtime:/etc/localtime:ro
  restart: unless-stopped
  privileged: true
  network_mode: host

Qualche nota sui parametri principali:

• image: stable — usa sempre l’ultima versione stabile. Se preferisci bloccare una versione specifica puoi usare ad esempio 2026.3.2
• network_mode: host — fondamentale per la discovery automatica dei dispositivi sulla rete locale (mDNS, SSDP)
• ./config:/config — mappa la cartella locale nel container, cosi i dati persistono anche quando riavvii o aggiorni il container
• privileged: true — necessario per alcune integrazioni hardware

Step 4 — Avvia Home Assistant

Dalla cartella ~/homeassistant esegui:

docker compose up -d

Docker scarica l’immagine di Home Assistant (circa 1-2 GB la prima volta) e avvia il container in background. Puoi seguire i log in tempo reale con:

docker compose logs -f

Aspetta fino a quando nei log compare qualcosa tipo Home Assistant initialized in X.Xs. Ci vogliono 1-3 minuti al primo avvio.

Step 5 — Prima configurazione e registrazione utente

Apri il browser e vai su http://localhost:8123. Vedrai la schermata di onboarding di Home Assistant. Da qui:

1. Crea il tuo account amministratore (nome, username, password)
2. Imposta il nome della casa e la posizione geografica
3. Home Assistant rileva automaticamente eventuali dispositivi gia presenti sulla rete

Step 6 — Installare HACS

HACS (Home Assistant Community Store) su Home Assistant Container si installa in modo leggermente diverso rispetto a HAOS, perche non abbiamo l’add-on store. Il metodo e via terminale, dentro il container.

Apri un nuovo tab del Terminale ed entra nel container:

docker exec -it homeassistant bash

Ora sei dentro il container. Esegui lo script di installazione ufficiale di HACS:

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

Quando lo script ha finito, esci dal container e riavvia Home Assistant:

exit
docker compose restart

Dopo il riavvio, vai su Impostazioni → Dispositivi e Servizi → Aggiungi Integrazione e cerca “HACS”. Segui la procedura di autorizzazione con il tuo account GitHub (necessario per usare HACS) e in pochi minuti trovi HACS nella sidebar.

Gestione del container: comandi utili

Una volta che hai tutto attivo, questi sono i comandi che userai piu spesso:

# Ferma il container
docker compose down

# Avvia (o riavvia) il container
docker compose up -d

# Visualizza i log in tempo reale
docker compose logs -f

# Aggiorna Home Assistant all'ultima versione stable
docker compose pull && docker compose up -d

Tutti i dati sono nella cartella ~/homeassistant/config — puoi aprirla direttamente in Finder o in VS Code per modificare i file YAML di configurazione.

Cosa puoi fare da qui

Con questo setup hai un ambiente Home Assistant a tutti gli effetti sul tuo Mac: puoi testare nuove configurazioni YAML prima di applicarle al sistema di produzione, sviluppare e testare Bubble Card e altre custom card senza rischi, sperimentare con integrazioni e temi, e affinare automazioni complesse in modo sicuro.

Se stai cercando di installare anche le WeSmart Custom Cards, questo e l’ambiente ideale: puoi iterare velocemente senza toccare nulla del tuo sistema principale.

L’unica cosa che manca rispetto a un’installazione HAOS completa sono gli Add-on. Per tutto il resto, e un ambiente Home Assistant a tutti gli effetti.