{"id":21081677,"url":"https://github.com/openvoiceos/ovos-installer","last_synced_at":"2026-05-15T00:16:35.489Z","repository":{"id":206081578,"uuid":"715783395","full_name":"OpenVoiceOS/ovos-installer","owner":"OpenVoiceOS","description":"Open Voice OS and/or HiveMind installer using Ansible with an intuitive and easy Text-based User Interface","archived":false,"fork":false,"pushed_at":"2025-03-21T13:57:06.000Z","size":2684,"stargazers_count":131,"open_issues_count":9,"forks_count":31,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-21T15:07:08.346Z","etag":null,"topics":["ai","ansible","container","devkit","docker","hivemind","hivemind-installer","installer","macos","mark1","mark2","openvoiceos","ovos","ovos-installer","rapsberrypi","tui","virtualenv","voice-assistant","windows","wsl2"],"latest_commit_sha":null,"homepage":"https://www.openvoiceos.org","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenVoiceOS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["OpenVoiceOS"],"patreon":"openvoiceos","liberapay":"OpenVoiceOS-Foundation","custom":"https://paypal.me/openvoiceos"}},"created_at":"2023-11-07T20:31:20.000Z","updated_at":"2025-03-21T13:57:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"baa7cf27-f63a-4d9a-a960-fc07eb3898a2","html_url":"https://github.com/OpenVoiceOS/ovos-installer","commit_stats":null,"previous_names":["smartgic/ovos-installer"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenVoiceOS%2Fovos-installer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenVoiceOS%2Fovos-installer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenVoiceOS%2Fovos-installer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenVoiceOS%2Fovos-installer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenVoiceOS","download_url":"https://codeload.github.com/OpenVoiceOS/ovos-installer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246085591,"owners_count":20721210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ansible","container","devkit","docker","hivemind","hivemind-installer","installer","macos","mark1","mark2","openvoiceos","ovos","ovos-installer","rapsberrypi","tui","virtualenv","voice-assistant","windows","wsl2"],"created_at":"2024-11-19T20:09:59.683Z","updated_at":"2026-05-15T00:16:34.760Z","avatar_url":"https://github.com/OpenVoiceOS.png","language":"Shell","funding_links":["https://github.com/sponsors/OpenVoiceOS","https://patreon.com/openvoiceos","https://liberapay.com/OpenVoiceOS-Foundation","https://paypal.me/openvoiceos"],"categories":[],"sub_categories":[],"readme":"# 🎉 Open Voice OS and HiveMind Installer 🎉\n\nInstaller for Open Voice OS (OVOS) and HiveMind on Linux and macOS. Supports interactive installs, scenario-based automation, and optional container deployment.\n\n## 🤖 What is Open Voice OS?\n\nOpen 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.\n\n## 🚀 Quickstart\n\nPrereqs: `curl`, `git`, and `sudo`. Run:\n\n```shell\nsudo sh -c \"$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)\"\n```\n\nIf you prefer to inspect before running, download the script first, review it, then execute it with `sudo sh installer.sh`.\n\nThis downloads and runs the installer interactively.\n\n\u003e 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.\n\n### ⚙️ Passing environment variables to the `curl` one-liner\n\nTo set environment variables when using the `curl` one-liner, use `sudo env ...` so the variables are visible to the installer:\n\n```shell\n# Enable debug logs (adds bash -x and increases Ansible verbosity)\nsudo env DEBUG=true sh -c \"$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)\"\n\n# Pick a different OVOS virtualenv Python version (default: 3.11)\nsudo env OVOS_VENV_PYTHON=3.12 sh -c \"$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)\"\n\n# Speed up repeated runs by reusing cached artifacts (useful for debugging)\nsudo env REUSE_CACHED_ARTIFACTS=true sh -c \"$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)\"\n\n# Forward proxy variables into generated launchd/systemd services\nsudo 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)\"\n```\n\n👉 Guide: [Howto - Begin your Open Voice OS journey with the OVOS installer](https://community.openconversational.ai/t/howto-begin-your-open-voice-os-journey-with-the-ovos-installer/14900)\n\n## 🍎 macOS support (Intel + Apple Silicon)\n\nmacOS installs use `launchd` service management and are currently supported with this matrix only:\n\n- `method: virtualenv`\n- `channel: alpha`\n\nPrerequisites:\n\n- Homebrew installed and available in `PATH`.\n- Bash 4+ installed with Homebrew (`brew install bash`) for the installer runtime.\n- Xcode Command Line Tools installed (`xcode-select --install`).\n- Microphone permission granted to your terminal app (System Settings \u003e Privacy \u0026 Security \u003e Microphone).\n\nYour 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.\n\n## 🐧 Supported Linux distributions\n\nThe installer has been tested on the following Linux distributions and versions:\n\n| Distribution        | Version   |\n| ------------------- | --------- |\n| AlmaLinux           | `\u003e= 8`    |\n| Arch                | `rolling` |\n| CachyOS             | `rolling` |\n| CentOS              | `\u003e= 8`    |\n| Debian GNU/Linux    | `\u003e= 10`   |\n| EndeavourOS         | `rolling` |\n| KDE Neon            | `\u003e=20.04` |\n| Fedora              | `\u003e= 37`   |\n| Linux Mint          | `\u003e= 21`   |\n| openSUSE Leap       | `\u003e= 15`   |\n| openSUSE Tumbleweed | `rolling` |\n| openSUSE Slowroll   | `rolling` |\n| Pop!\\_OS            | `\u003e=22.04` |\n| Manjaro             | `rolling` |\n| Raspbian            | `10`      |\n| Raspberry Pi OS     | `\u003e= 11`   |\n| Rocky Linux         | `\u003e=8`     |\n| Ubuntu              | `\u003e=20.04` |\n| WSL2                | `20.04`   |\n| Zorin OS            | `\u003e= 16`   |\n\nNote: '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.\n\n## 🔄 Update\n\nTo 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?\"_.\n\n## ⚙️ Service management\n\n### 🍎 macOS (launchd wrapper)\n\nUse the `ovos` wrapper command:\n\n```shell\novos restart ovos-listener\novos stop ovos\novos start ovos-audio\novos restart ovos-core\n```\n\nAdditional commands:\n\n```shell\novos status ovos-core\novos status ovos\novos list\n```\n\n`ovos` is a meta target for all installed OVOS user services on macOS.\n\n### 🐧 Linux (systemd)\n\nWhen 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.\n\n### 📋 List the systemd unit files\n\nUser scope (default):\n\n```shell\nsystemctl --user list-units \"*ovos*\"\n```\n\nSystem scope (performance/realtime tuning):\n\n```shell\nsudo systemctl list-units \"*ovos*\"\n```\n\n`ovos-phal-admin` always runs as `root`. The main `ovos` service runs in user or system scope depending on your install.\n\n### 🟢 Start Open Voice OS\n\nUser scope (default):\n\n```shell\nsystemctl --user start ovos\nsudo systemctl start ovos-phal-admin\n```\n\nSystem scope (performance/realtime tuning):\n\n```shell\nsudo systemctl start ovos\nsudo systemctl start ovos-phal-admin\n```\n\n### 🔴 Stop Open Voice OS\n\nUser scope (default):\n\n```shell\nsystemctl --user stop ovos\nsudo systemctl stop ovos-phal-admin\n```\n\nSystem scope (performance/realtime tuning):\n\n```shell\nsudo systemctl stop ovos\nsudo systemctl stop ovos-phal-admin\n```\n\n## 🎙️ Audio calibration tool\n\nIf 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.\n\n```shell\nscripts/audio-calibrate.sh\n```\n\nTo apply the recommended capture volume automatically:\n\n```shell\nscripts/audio-calibrate.sh --apply\n```\n\nBluetooth 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.\n\n## 🤖 Automated install\n\nThe 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.\n\nHere is an example of a scenario to install Open Voice OS within Docker containers on a Raspberry Pi 4B with default skills.\n\n```shell\nmkdir -p ~/.config/ovos-installer\ncat \u003c\u003cEOF \u003e ~/.config/ovos-installer/scenario.yaml\n---\nuninstall: false\nmethod: containers\nchannel: testing\nprofile: ovos\nfeatures:\n  skills: true\n  extra_skills: false\nraspberry_pi_tuning: true\nshare_telemetry: true\nshare_usage_telemetry: true\nEOF\n```\n\n### Configuration options explained\n\n- `uninstall`: Set to `true` to uninstall instead of install.\n- `method`: Installation method (`containers` for Docker, `virtualenv` for Python virtual environment). On macOS and Mark 2 hardware, use `virtualenv` only.\n- `channel`: Release channel (`testing`, `alpha`). On macOS, use `alpha` only.\n- `profile`: Installation profile (`ovos` for standard setup).\n- `features.skills`: Install default voice skills.\n- `features.extra_skills`: Install additional community skills.\n- `features.llm`: Enable OVOS Persona LLM fallback.\n- `llm.api_url`: OpenAI-compatible API base URL (required when `features.llm` is true).\n- `llm.key`: API key for the selected endpoint (required when `features.llm` is true).\n- `llm.model`: Model name to use for completions (required when `features.llm` is true).\n- `llm.persona`: System prompt/persona text for `ovos-persona` (required when `features.llm` is true).\n- `raspberry_pi_tuning`: Enable maximum-performance tuning for Raspberry Pi hardware (includes an overclocking prompt).\n- `share_telemetry`: Allow sharing anonymous usage statistics.\n- `share_usage_telemetry`: Allow sharing detailed usage data.\n\nExample scenarios live in the [scenarios](https://github.com/OpenVoiceOS/ovos-installer/tree/main/scenarios) directory of this repository.\n\n## 🧩 Ansible role map\n\nThe installer is modular. The top-level wrapper role (`ovos_installer`) orchestrates focused roles, roughly in this order:\n\n- `ovos_facts`: Shared installer facts (boot dir, NetworkManager, systemd paths)\n- `ovos_timezone`: Detect and configure system timezone\n- `ovos_config`: Configuration defaults and `mycroft.conf` generation\n- `ovos_sound`: Sound server setup (PipeWire/PulseAudio)\n- `ovos_virtualenv`: Python virtualenv provisioning and package install\n- `ovos_containers`: Docker/compose provisioning and deployment\n- `ovos_services`: Systemd units + handlers (user or system scope)\n- `ovos_telemetry`: Optional telemetry submission\n- `ovos_storage_tuning`: fstab/log2ram/tmpfs tuning\n- `ovos_audio_tuning`: PipeWire/WirePlumber tuning\n- `ovos_python`: Python runtime tuning (mimalloc, env)\n- `ovos_performance_tuning`: governor, I/O, zram, sysctl, NUMA, limits\n- `ovos_network_tuning`: wireless power + DNS caching\n- `ovos_finalize`: Post-install cleanup and drift notice\n- `ovos_hardware_mark1` / `ovos_hardware_mark2`: hardware-specific roles (applied when detected)\n\n## ❌ Uninstall\n\nUninstalling Open Voice OS removes installed components, configurations, and services. Back up any important data first.\n\n```shell\n# One-liner\nsudo sh -c \"$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)\" installer.sh --uninstall\n\n# One-liner with env vars\nsudo env DEBUG=true sh -c \"$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)\" installer.sh --uninstall\n```\n\n## 🖼️ Screenshots\n\n![Screenshot 1](docs/images/screenshot_1.png)\n\n![Screenshot 2](docs/images/screenshot_3.png)\n\n![Screenshot 3](docs/images/screenshot_4.png)\n\n![Screenshot 4](docs/images/screenshot_5.png)\n\n![Screenshot 5](docs/images/screenshot_6.png)\n\n![Screenshot 6](docs/images/screenshot_7.png)\n\n![Screenshot 7](docs/images/screenshot_8.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenvoiceos%2Fovos-installer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenvoiceos%2Fovos-installer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenvoiceos%2Fovos-installer/lists"}