🎉 Open Voice OS and HiveMind Installer 🎉

April 27, 2026 · View on GitHub

Installer for Open Voice OS (OVOS) and HiveMind on Linux and macOS. Supports interactive installs, scenario-based automation, and optional container deployment.

🤖 What is Open Voice OS?

Open Voice OS (OVOS) is an open-source voice assistant platform focused on privacy and customization. HiveMind extends OVOS with distributed voice processing across multiple devices.

🚀 Quickstart

Prereqs: curl, git, and sudo. Run:

sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)"

If you prefer to inspect before running, download the script first, review it, then execute it with sudo sh installer.sh.

This downloads and runs the installer interactively.

Heads-up: OVOS targets a supported Python runtime in its virtualenv (default 3.11). The installer uses uv to provision that version if it is not already available. You can override with OVOS_VENV_PYTHON if you want to use a different version that is available on your system.

⚙️ Passing environment variables to the curl one-liner

To set environment variables when using the curl one-liner, use sudo env ... so the variables are visible to the installer:

# Enable debug logs (adds bash -x and increases Ansible verbosity)
sudo env DEBUG=true sh -c "$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)"

# Pick a different OVOS virtualenv Python version (default: 3.11)
sudo env OVOS_VENV_PYTHON=3.12 sh -c "$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)"

# Speed up repeated runs by reusing cached artifacts (useful for debugging)
sudo env REUSE_CACHED_ARTIFACTS=true sh -c "$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)"

# Forward proxy variables into generated launchd/systemd services
sudo env HTTPS_PROXY=http://proxy.example:3128 HTTP_PROXY=http://proxy.example:3128 NO_PROXY=localhost,127.0.0.1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)"

👉 Guide: Howto - Begin your Open Voice OS journey with the OVOS installer

🍎 macOS support (Intel + Apple Silicon)

macOS installs use launchd service management and are currently supported with this matrix only:

  • method: virtualenv
  • channel: alpha

Prerequisites:

  • Homebrew installed and available in PATH.
  • Bash 4+ installed with Homebrew (brew install bash) for the installer runtime.
  • Xcode Command Line Tools installed (xcode-select --install).
  • Microphone permission granted to your terminal app (System Settings > Privacy & Security > Microphone).

Your login shell can remain zsh. The installer also deploys a zsh wrapper (~/.config/ovos-installer/ovos-launchd.zsh) and sources it from ~/.zshrc so you can manage launchd services with ovos ... commands.

🐧 Supported Linux distributions

The installer has been tested on the following Linux distributions and versions:

DistributionVersion
AlmaLinux>= 8
Archrolling
CachyOSrolling
CentOS>= 8
Debian GNU/Linux>= 10
EndeavourOSrolling
KDE Neon>=20.04
Fedora>= 37
Linux Mint>= 21
openSUSE Leap>= 15
openSUSE Tumbleweedrolling
openSUSE Slowrollrolling
Pop!_OS>=22.04
Manjarorolling
Raspbian10
Raspberry Pi OS>= 11
Rocky Linux>=8
Ubuntu>=20.04
WSL220.04
Zorin OS>= 16

Note: 'rolling' indicates a rolling release distribution with no fixed version number. Role metadata in ansible/roles/*/meta/main.yml lists the base OS families/versions (e.g., Debian/Ubuntu/EL/Fedora/Arch/Suse) that cover these distributions.

🔄 Update

To update, optionally back up your configuration (~/.config/mycroft/mycroft.conf or ~/ovos/config/mycroft.conf) and re-run the installer. When prompted, answer "No" to "Do you want to uninstall Open Voice OS?".

⚙️ Service management

🍎 macOS (launchd wrapper)

Use the ovos wrapper command:

ovos restart ovos-listener
ovos stop ovos
ovos start ovos-audio
ovos restart ovos-core

Additional commands:

ovos status ovos-core
ovos status ovos
ovos list

ovos is a meta target for all installed OVOS user services on macOS.

🐧 Linux (systemd)

When the virtualenv method is chosen (default), systemd unit files are created to manage OVOS services. Some installs run services in system scope for performance/realtime tuning; use the matching commands below.

📋 List the systemd unit files

User scope (default):

systemctl --user list-units "*ovos*"

System scope (performance/realtime tuning):

sudo systemctl list-units "*ovos*"

ovos-phal-admin always runs as root. The main ovos service runs in user or system scope depending on your install.

🟢 Start Open Voice OS

User scope (default):

systemctl --user start ovos
sudo systemctl start ovos-phal-admin

System scope (performance/realtime tuning):

sudo systemctl start ovos
sudo systemctl start ovos-phal-admin

🔴 Stop Open Voice OS

User scope (default):

systemctl --user stop ovos
sudo systemctl stop ovos-phal-admin

System scope (performance/realtime tuning):

sudo systemctl stop ovos
sudo systemctl stop ovos-phal-admin

🎙️ Audio calibration tool

If wake word detection is weak or inconsistent, run the calibration helper to tune your microphone input. The tool records short samples (silence, speech, wake word), measures signal levels, and recommends capture volume and listener multiplier values.

scripts/audio-calibrate.sh

To apply the recommended capture volume automatically:

scripts/audio-calibrate.sh --apply

Bluetooth headsets work too, but the mic typically needs the HFP/HSP profile. The installer will attempt to switch profiles automatically when a Bluetooth mic is the default input.

🤖 Automated install

The installer supports non-interactive installation via a scenario file at ~/.config/ovos-installer/scenario.yaml. This is useful for scripting or deploying to multiple devices.

Here is an example of a scenario to install Open Voice OS within Docker containers on a Raspberry Pi 4B with default skills.

mkdir -p ~/.config/ovos-installer
cat <<EOF > ~/.config/ovos-installer/scenario.yaml
---
uninstall: false
method: containers
channel: testing
profile: ovos
features:
  skills: true
  extra_skills: false
raspberry_pi_tuning: true
share_telemetry: true
share_usage_telemetry: true
EOF

Configuration options explained

  • uninstall: Set to true to uninstall instead of install.
  • method: Installation method (containers for Docker, virtualenv for Python virtual environment). On macOS and Mark 2 hardware, use virtualenv only.
  • channel: Release channel (testing, alpha). On macOS, use alpha only.
  • profile: Installation profile (ovos for standard setup).
  • features.skills: Install default voice skills.
  • features.extra_skills: Install additional community skills.
  • features.llm: Enable OVOS Persona LLM fallback.
  • llm.api_url: OpenAI-compatible API base URL (required when features.llm is true).
  • llm.key: API key for the selected endpoint (required when features.llm is true).
  • llm.model: Model name to use for completions (required when features.llm is true).
  • llm.persona: System prompt/persona text for ovos-persona (required when features.llm is true).
  • raspberry_pi_tuning: Enable maximum-performance tuning for Raspberry Pi hardware (includes an overclocking prompt).
  • share_telemetry: Allow sharing anonymous usage statistics.
  • share_usage_telemetry: Allow sharing detailed usage data.

Example scenarios live in the scenarios directory of this repository.

🧩 Ansible role map

The installer is modular. The top-level wrapper role (ovos_installer) orchestrates focused roles, roughly in this order:

  • ovos_facts: Shared installer facts (boot dir, NetworkManager, systemd paths)
  • ovos_timezone: Detect and configure system timezone
  • ovos_config: Configuration defaults and mycroft.conf generation
  • ovos_sound: Sound server setup (PipeWire/PulseAudio)
  • ovos_virtualenv: Python virtualenv provisioning and package install
  • ovos_containers: Docker/compose provisioning and deployment
  • ovos_services: Systemd units + handlers (user or system scope)
  • ovos_telemetry: Optional telemetry submission
  • ovos_storage_tuning: fstab/log2ram/tmpfs tuning
  • ovos_audio_tuning: PipeWire/WirePlumber tuning
  • ovos_python: Python runtime tuning (mimalloc, env)
  • ovos_performance_tuning: governor, I/O, zram, sysctl, NUMA, limits
  • ovos_network_tuning: wireless power + DNS caching
  • ovos_finalize: Post-install cleanup and drift notice
  • ovos_hardware_mark1 / ovos_hardware_mark2: hardware-specific roles (applied when detected)

❌ Uninstall

Uninstalling Open Voice OS removes installed components, configurations, and services. Back up any important data first.

# One-liner
sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)" installer.sh --uninstall

# One-liner with env vars
sudo env DEBUG=true sh -c "$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)" installer.sh --uninstall

🖼️ Screenshots

Screenshot 1

Screenshot 2

Screenshot 3

Screenshot 4

Screenshot 5

Screenshot 6

Screenshot 7