Setup

September 2, 2026 · View on GitHub

1. Provision a HiveMind client on the hub

The integration needs an admin client key and password on the hivemind-core hub, with the message-type allowlist from permissions. Add the client on the hub before you configure Home Assistant.

2. Install the integration

Copy the hivemind folder into your Home Assistant custom_components directory:

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

Restart Home Assistant.

Prerelease requirement

This integration depends on a prerelease of hivemind_bus_client. Stock Home Assistant does not install prerelease packages, so a plain add of the integration fails with RequirementsNotFound. Before you add the integration, pre-install the dependency into the Home Assistant environment with prerelease resolution enabled, for example:

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 restart Home Assistant and add the integration. This requirement stands until the HiveMind stack ships a stable release.

3. Add the integration

In Home Assistant, go to Settings → Devices & Services → Add Integration → HiveMind.

Fill in the config flow:

  • Device type: agent, media_player, or voice_assistant (see configuration).
  • Name: a friendly name for the device.
  • Host: the HiveMind hub address — a bare hostname or IP (e.g. 192.168.1.10) or a ws:///wss:// URL if you need to force the scheme (wss:// for TLS). Port is a separate field, default 5678.
  • Access key / Password: the client credentials you provisioned in step 1.
  • Site id, legacy audio, allow self-signed: optional.

The form checks the connection before it saves the entry. If the hub is unreachable you get "cannot connect". If it rejects the credentials you get "invalid auth". Either way, you find out immediately instead of from a silent failure later.

4. Verify

Once added, the entities for the chosen device type appear under the new HiveMind device: a connection sensor, buttons, switches, and, depending on device type, a media player, notify, status sensors, and a listening-mode select. See entities.

If the connection sensor stays off, check that the hub is reachable, the client key is admin-privileged, and the required message types are allowed.

Home · Configuration →