HiveMind Integration for Home Assistant

September 3, 2026 · View on GitHub

A Home Assistant custom integration (domain: hivemind) that connects Home Assistant to an OpenVoiceOS instance over the HiveMind protocol and exposes OVOS as Home Assistant entities. You can install it through HACS (as a custom repository) or by hand.

The integration does more than send voice commands. It controls the OVOS device at a system level: audio playback, volume, microphone, sleep and wake, and system power. It does this by injecting low-level bus messages over the HiveMind link.

Where it sits

Home Assistant connects to a HiveMind hub (hivemind-core) that runs alongside an OVOS instance, using a HiveMind client key. Because the integration injects low-level bus messages instead of only utterances, that client must have admin privileges and the message-type allowlist described under Permissions Required.

Prerequisites

  • A running HiveMind hub (hivemind-core) reachable from Home Assistant.
  • An admin-privileged HiveMind client key and password registered on the hub for Home Assistant (see Permissions Required).
  • Home Assistant with access to its config/custom_components/ directory.
  • The integration declares the runtime requirement hivemind_bus_client>=1.0.16a1, a prerelease — see Prerelease requirement below.

Installation

HACS (custom repository)

  1. Add https://github.com/JarbasHiveMind/hivemind-homeassistant as a custom repository (category Integration).
  2. Install HiveMind.
  3. Restart Home Assistant.

Manual

  1. Copy the hivemind folder into your Home Assistant custom_components directory:

    mkdir -p /config/custom_components
cp -r custom_components/hivemind /config/custom_components/

  2. Restart Home Assistant.

Prerelease requirement

This integration depends on prerelease packages. Its dependency closure pulls in poorman-handshake, whose required version is a prerelease, so the integration must be installed in an environment where prerelease resolution is enabled. A stock Home Assistant add flow, or a plain pip install that does not enable prereleases, fails to resolve the dependencies and reports RequirementsNotFound.

Install into an environment that allows prereleases, for example:

uv pip install --prerelease=allow "hivemind_bus_client>=1.0.16a1"
# or
pip install --pre "hivemind_bus_client>=1.0.16a1"

In a Home Assistant container, run the equivalent pip install --pre command inside the container (or its virtual environment) before you add the integration.

This requirement stands until the HiveMind stack ships stable releases, at which point stock resolution succeeds without the prerelease flag.

Add the integration

Go to Settings → Devices & Services → Add Integration → HiveMind. The config flow checks the hub connection before it saves the entry, so a bad host or credential shows a clear cannot connect or invalid auth error instead of a silent failure.

Configuration fields

The config flow asks for these fields when you add the integration:

FieldDefaultDescription
device_typevoice_assistantWhich OVOS capabilities to expose (see below).
namen/aFriendly name for the device in Home Assistant.
hostn/aHiveMind hub address — a bare hostname/IP (e.g. 192.168.1.10) or a ws:///wss:// URL to force the scheme.
port5678HiveMind WebSocket port; a separate field from host.
access_keyn/aHiveMind client access key.
passwordn/aHiveMind client password.
site_idemptyOptional OVOS site id; leave blank if you have one hub.
allow_self_signedfalseAccept a self-signed TLS certificate.

Device types

The device_type field controls which platforms Home Assistant sets up:

TypeExposes
agentbinary sensors, buttons, switches (text input and output only).
media_playerthe above, plus notify and media_player.
voice_assistantthe above, plus select and sensor (full mic, VAD, and STT device).

See docs/ for the full setup, entity, and permissions guide.

Usage

Once you add a HiveMind device, its entities appear in Home Assistant: a connection sensor, control buttons and switches, and — depending on device_type — a media player, a notify service, status sensors, and a listening-mode selector.

Home Assistant entities

Send text to the OVOS instance with the notify service so it speaks the text through TTS. Control playback with the media_player entity, which maps Home Assistant MediaType values to OVOS OCP media types (music, video, movie, episode, TV channel, game, and others). It also works with sources exposed by ovos-skill-music-assistant.

Media player entity

Permissions Required

This integration does more than send voice queries: it injects and controls bus messages directly. The client connecting to HiveMind must have admin privileges and permission to use the following message types.

ovos-core

  • mycroft.stop
  • mycroft.skills.is_alive
  • mycroft.skills.is_ready

ovos-dinkum-listener

  • mycroft.voice.is_alive
  • mycroft.voice.is_ready
  • mycroft.mic.listen
  • mycroft.mic.mute
  • mycroft.mic.unmute
  • mycroft.mic.get_status
  • recognizer_loop:sleep
  • recognizer_loop:wake_up
  • recognizer_loop:state.get
  • recognizer_loop:state.set

ovos-gui

  • mycroft.gui_service.is_alive
  • mycroft.gui_service.is_ready

ovos-audio

  • speak
  • mycroft.audio.is_alive
  • mycroft.audio.is_ready
  • mycroft.audio.speak.status

OCP (OpenVoiceOS Common Play)

  • ovos.common_play.status
  • ovos.common_play.player.status (legacy OCP audio service; queried until flag day)
  • ovos.common_play.track_info
  • ovos.common_play.get_track_length
  • ovos.common_play.get_track_position
  • ovos.common_play.playlist.queue
  • ovos.common_play.resume
  • ovos.common_play.pause
  • ovos.common_play.stop
  • ovos.common_play.previous
  • ovos.common_play.next
  • ovos.common_play.set_track_position
  • ovos.common_play.playlist.clear
  • ovos.common_play.shuffle.set
  • ovos.common_play.shuffle.unset
  • ovos.common_play.repeat.set
  • ovos.common_play.repeat.unset

PHAL

  • mycroft.phal.is_alive
  • mycroft.phal.is_ready

ovos-phal-plugin-alsa

  • mycroft.volume.get
  • mycroft.volume.increase
  • mycroft.volume.decrease
  • mycroft.volume.mute
  • mycroft.volume.unmute

ovos-phal-plugin-system

  • system.reboot
  • system.shutdown
  • system.mycroft.service.restart
  • system.ssh.status

ovos-phal-plugin-camera

(work in progress)

  • ovos.phal.camera.ping
  • ovos.phal.camera.get
  • ovos.phal.camera.open
  • ovos.phal.camera.close

Security notes

  • This integration directly manipulates OpenVoiceOS state.
  • Proper permission management is critical for security.
  • Only connect trusted Home Assistant instances to your HiveMind hub.

License

MIT