Linux Voice Assistant turns a spare Pi into a Home Assistant satellite

A satellite that impersonates an ESPHome device

linux-voice-assistant is an experimental voice satellite for Home Assistant, built to talk the ESPHome protocol through the aioesphomeapi library. That choice shapes everything about how it is deployed. A Home Assistant installation discovers it through the ESPHome integration automatically, with no custom component to install and no manual entry of a host and port. The project exists because the usual voice satellite hardware is a microcontroller with little compute, and the stated advantage of running on a full Linux system is that wake word detection happens locally, using OpenWakeWord or MicroWakeWord, and that some processing can stay on the device. The project is a project from the Open Home Foundation, licensed under Apache-2.0, with the package metadata classifying it as Development Status 3 - Alpha.

The hardware floor is modest but not trivial

The requirements are listed without embellishment. The device must support 16kHz mono audio for the microphone, the CPU needs to be at least 1GHz, memory has a minimum of 512MB, and storage is around 4GB for the operating system and the software together. The OS has to be linux/amd64 or linux/aarch64, and the prebuilt Docker image covers both architectures. The audio path runs through PulseAudio, with PipeWire treated as an optional direction for experimentation rather than a requirement. For hardware, the guidance is to prefer a far-field microphone array over a basic mic, and two setups are recommended today: a Raspberry Pi Zero 2W with the Satellite1 HAT board, or at least a Raspberry Pi 3 with the Respeaker Lite, which currently has a problem with the Zero 2W. The reasoning behind the array recommendation is spelled out, because the onboard XMOS DSP runs noise suppression, acoustic echo cancellation, interference cancellation and automatic gain control before the audio ever reaches the software.

Three installation paths, and the add-on is not public yet

For the Docker and systemd setups the configuration is a set of environment variables, and the repository ships a template you copy to .env and edit. The PulseAudio socket paths are the part that most often needs changing:

LVA_PULSE_SERVER="/run/user/${LVA_USER_ID}/pulse/native"

Installation depends on what you are running. For Home Assistant OS, the project provides a finished Assist Satellite app, formerly an add-on, built on the same runtime, which turns the HA host itself into a satellite. The catch is stated plainly in the README: the OHF-Voice apps repository has to be added manually to the App Store repository inside Home Assistant first, and the app is not yet published in the official add-on repository. For Raspberry Pi users there is a prebuilt SD card image to flash, built through the PiCompose project, whose documentation also holds the longer list of compatible hardware. For everyone else there are Docker and systemd instructions in the installation document, and the note that each parameter has a matching environment variable for the Docker and systemd setups. Once installed, the satellite is discovered by Home Assistant through the ESPHome integration.

Docker runs the assistant on the host network with PulseAudio mounted

The compose file shows the deployment shape in detail. Two services are defined, a short-lived fix-permissions job that chowns the wakeword, configuration and custom sound volumes so the non-root user can write to them, and the assistant itself. The image is parameterised through environment variables, defaulting to the GitHub Container Registry build with a latest tag, and the container runs with network_mode set to host, which is how the satellite reaches the Home Assistant instance and the ESPHome discovery path without extra port mapping. It runs as the configured user id and group, joins the audio group, and has the SYS_NICE capability added, with an inline comment noting the priority is for the audio process. Four named volumes hold wake word data, custom wake words, configuration and custom sounds, and the PulseAudio environment variables XDG_RUNTIME_DIR, PULSE_SERVER and PULSE_COOKIE are all overridable. The .env.example file spells out the same knobs, including a client name, the preferences file path and the API port.

The container image is Python 3.13 on a slim base

The Dockerfile pins the runtime precisely. The base is python:3.13-slim-trixie, with LANG set to C.UTF-8, DEBIAN_FRONTEND set to noninteractive and PYTHONUNBUFFERED enabled, and it carries OpenContainers labels for the authors, description, documentation link, licence, source and title. The package list is annotated line by line, which makes the dependency story easy to audit: avahi-utils for zeroconf and mDNS discovery by Home Assistant, pulseaudio-utils required by the soundcard library for audio input and output, alsa-utils for device management, the pipewire packages for PipeWire support, build-essential to compile the wake word feature, libmpv-dev and libasound2-plugins for python-mpv playback, iproute2 for the port check in the entrypoint and procps for the process check in the healthcheck. The dependency list in pyproject.toml mirrors that, with aioesphomeapi pinned at 45.3.1, websockets at 12, numpy, python-mpv, soundcard and the two wake word packages.

Announcements, timers and a websocket channel for hardware

The feature list shows what the satellite does once connected. It supports announcements, start and continue conversation, and timers, which are the Home Assistant actions a satellite needs to be useful rather than decorative. It can carry several wake words across several languages. Beyond the voice path, it exposes a websocket API for peripherals, documented separately in the repository under the peripheral API document, so buttons, LEDs and similar hardware can drive the assistant. The examples directory shows what that means in practice, with hardware-specific folders for the Jabra Speak 410, the Peripheral web console, several ReSpeaker HAT and USB microphone arrays, and the Satellite1 HAT board, alongside libmpv smoke test scripts. The offline code path runs on a full operating system, which is what makes these peripheral integrations possible in a way a microcontroller satellite does not allow.

Against a commercial satellite, and what alpha costs you

The realistic alternative is a commercial ESPHome voice satellite, the microphone board that Home Assistant discovers out of the box, or an ESPHome build running on an ESP32 that you configure yourself. The difference in approach is where the compute sits and who maintains the firmware. A microcontroller satellite is cheaper, smaller and already supported by the integration, and the ESP32 route lets you write your own firmware with the wake word options that board supports. linux-voice-assistant trades that for a full Linux system with local detection using OpenWakeWord or MicroWakeWord, room for extra integrations on the same box, and the flexibility to experiment with PipeWire as the README puts it. The costs are visible in the documentation: alpha classification, a manual repository step for the Home Assistant OS app, a Docker or systemd setup rather than a single add-on, and a device that needs a 16kHz mono input path and about 4GB of storage.

Editorial conclusion

linux-voice-assistant fits a Home Assistant user with spare compute who wants local wake word detection, the same ESPHome discovery path as a commercial microphone board, and a Linux box rather than a microcontroller. It does not fit a user who wants a one-click install from the official add-on repository, since the app still has to be added from the OHF-Voice apps repository manually, and it does not fit a machine without a 16kHz mono microphone path through PulseAudio. Verify first that your board is linux/amd64 or linux/aarch64, that your audio stack exposes a usable input device, and that the alpha classification in the package metadata matches your tolerance for rough edges.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. OHF-Voice/linux-voice-assistant on GitHub
4. README
5. Releases