⚠️ Note: This stack is intended to be run in a containerized Docker environment.
If you are installing Home Assistant or its components outside Docker (e.g., via Home Assistant OS, Supervised, or Python virtualenv),
please refer to the official documentation instead: Getting Started with Home Assistant
This repo contains a self-hosted voice assistant stack that runs entirely on your machine - no cloud required, no subscriptions, and no surveillance.
It uses Docker Compose to orchestrate services like Home Assistant, Whisper for speech recognition, Piper for text-to-speech, and OpenWakeWord for wake word detection. Each service is GPU-accelerated for fast, low-latency voice interaction. This stack assumes you currently have Ollama installed locally - See section below on Ollama for further details.
| Service | Purpose | GPU Support | Notes |
|---|---|---|---|
homeassistant |
Smart home brain | ❌ | Controls devices and automations |
whisper |
Speech-to-text | ✅ | Whisper model w/ CUDA support |
piper |
Text-to-speech | ✅ | CUDA-accelerated voice synthesis |
openwakeword |
Wake word detection | ✅ | Useful for ESP32/Atom devices |
.
├── docker-compose.yml # Core stack config
├── homeassistant_config/ # HA configuration volume
├── whisper-data/ # Whisper model data
├── piper-data/ # Piper voice data
└── wakeword-data/ # Custom wake word files
Note:
ℹ️ Docker will auto-create the volume folders (like
./whisper-data,./piper-data, etc.) if they don’t exist.
You don’t need to manually create them — they’ll show up after your firstdocker compose up.
Make sure you have Docker and NVIDIA GPU support set up (via
nvidia-container-toolkit).
-
Clone this repo:
git clone https://github.com/RoyalCities/RC-Home-Assistant-Low-VRAM.git cd RC-Home-Assistant-Low-VRAM -
Start everything:
docker compose up -d
-
Access Home Assistant:
- Navigate to http://localhost:8123 in your browser.
Each AI service uses NVIDIA GPU acceleration via the following Compose directive:
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: ["gpu", "utility", "compute"]This speeds up Whisper, Piper, and OpenWakeWord drastically compared to CPU-based inference. This ensures the entire stack hits your GPU.
💡 Make sure your NVIDIA drivers and
nvidia-dockerruntime are properly installed.
devices:
- "/dev/hci0"This line in the homeassistant container enables Bluetooth support — useful for presence detection, BLE sensors, or Matter-over-Bluetooth. It only works on Linux hosts.
🪟 If you're on Windows or macOS, you can safely remove this line.
network_mode: hostHome Assistant uses host networking to enable local discovery (e.g., mDNS, SSDP, uPnP) for devices like Google Home, Chromecast, and other smart devices.
⚠️ This setting is only relevant if you're running Home Assistant inside Docker.
If you're running Home Assistant natively (e.g., via Home Assistant OS, Supervised, or in a VM), this is handled automatically — you don’t need to configure network mode manually.
⚠️ Docker limitation on Windows/macOS:
network_mode: hostonly works properly on Linux.
On other platforms, local device discovery may not work unless you use bridged networking, WSL2, or run HA in a Linux-based VM.
This stack includes openwakeword to support custom wake words, using .tflite models trained or downloaded locally.
- ✅ You're using ESP32‑S3 devices like:
- M5Stack ATOM Echo
- ESP32‑S3‑BOX‑3
- ✅ You want to stream audio to HA and use custom wake words
- ❌ You're using a Home Assistant Voice Preview Edition (Voice PE) unit
Voice PE uses the
microWakeWordengine, which runs entirely on-device and only supports built-in wake words like:- "Okay Nabu"
- "Hey Jarvis"
- "Hey Mycroft"
Including openwakeword future-proofs your setup for advanced use cases, but it's not currently used by Voice PE. Hopefully official support for openwakeword comes at some point in the future to HA Voice Preview.
- You can change the Whisper model size (
tiny,small,medium) via theMODEL=environment variable. The default model I have set up is perfectly capable and ensures minimal VRAM hit but feel free to try different ones. - Piper supports multiple voice presets — I set a default one for the
--voiceargument you change this within the HA GUI itself. - Feel free to remove services you don’t need (e.g.,
openwakeword) by commenting them out indocker-compose.yml.
This stack assumes Ollama is installed and running locally on your host machine, outside of Docker.
Ollama is not included in this Compose stack.
Make sure Ollama is running and listening on http://localhost:11434 before starting Home Assistant.
You will also need to configure your preferred AI model manually within Home Assistant under Settings → Voice Assistants → Assist → Conversation Agent.
💡 My model recommendations include a 4-bit quantized model that fits the entire stack within ~9GB of VRAM — ideal for local GPU setups.
Once you're up and running, you can add advanced voice features:
Add memory to your assistant — it can remember facts you tell it (“remember that my birthday is January 1st”) and log recent actions (“I launched YouTube on the TV”) for smarter context.
Add natural follow-up support. For example:
“Turn on the TV.”
“The TV is now on. Would you like to open an app?”
💡 These modules work independently — but together, they create a true multi-turn, memory-capable voice assistant.
MIT License for code. Any media/design content is CC-BY 4.0 unless noted otherwise.
- Home Assistant
- Special thanks to the Home Assistant Voice team for making local voice a reality.