Skip to content

OpenVoiceOS Technical Manual

The complete guide to using, building on, and understanding the OVOS voice assistant, from your first install to the deepest internals.

In a nutshell

OpenVoiceOS (OVOS) is a free, open-source voice assistant you run yourself. It is an open alternative to Alexa or Google Assistant. This manual covers every layer of it: installing a ready-made device, writing your first skill, and the internals of the messagebus and intent pipeline underneath. Pick a path below that matches what you want to do. You don't need to read it front to back.

OVOS Logo

What is OpenVoiceOS?

OpenVoiceOS (OVOS) is a free, open-source, privacy-respecting voice assistant. Think of it as an open alternative to Alexa or Google Assistant that you control. It listens for a wake word, understands what you ask, and responds with speech, and optionally a screen.

OVOS code follows a universal donor policy, predominantly Apache-2.0/BSD; exceptions are listed on License.

You can run it on a Raspberry Pi, a desktop, or a server. It is modular, built from many small, swappable pieces called plugins and skills. You can change how it hears, thinks, and speaks, or teach it brand-new abilities.

New to all this? Don't worry.

This manual covers everything from "I just want it working" to "I'm rewriting the intent pipeline." You don't need to read it front to back. Pick the path below that matches what you want to do. Unfamiliar word? Check the Glossary.

OVOS is do-it-yourself

There's no phone app and no plug-and-play appliance to buy. You get OVOS running by flashing an SD-card image or working from a terminal. See below. It's not hard, but it is hands-on.

Start here

If you just want a working voice assistant with the least fuss, install Raspberry Pi OS on a Raspberry Pi and run the ovos-installer, a guided wizard.

Starting from a Raspberry Pi still in its box, do this first. Write Raspberry Pi OS to an SD card with Raspberry Pi Imager, the official tool. In the Imager, open the settings before writing and set a username and password, your Wi-Fi network, and enable SSH. Without SSH you need a keyboard and monitor attached to the Pi. Raspberry Pi's own getting-started guide covers this in full. Then boot the Pi, connect to it, and run the installer.

The flash-and-boot raspOVOS image is an alternative, but its stable images date from mid-2025 and are unmaintained, so check its status first. Everyone else, pick your path in the grid below.

Choose your path

Accessibility

OVOS is voice-first by design, which makes it a strong fit for assistive use. See the Accessibility statement for specifics.

How OVOS is organized

OVOS is not one program. It's a small team of cooperating services that talk to each other over a shared messagebus. Knowing these components will make the rest of the manual easier to follow:

Maturity badges

Most component and plugin pages open with a maturity badge (e.g. ⬤⬤⬤⬤◯ Stable), and the plugin catalogs carry a Maturity column. It tells you how much a component can be relied on, judged from repository health rather than version number. See the Maturity Scale.

Piece In plain terms Learn more
Listener Hears the wake word and records your speech Speech Service
STT Turns your speech into text STT plugins
ovos-core The "brain": decides which skill should answer ovos-core
Skills The abilities (weather, timers, music…) Skill development
TTS Turns the reply text back into speech TTS plugins
GUI Shows an optional screen or visuals (legacy/deprecated, current status) GUI Service
messagebus The shared channel they all talk over messagebus Service

Plugins vs. Skills: the two ways to extend OVOS

A skill adds an ability ("set a timer", "play the news"). A plugin swaps out a building block (a different speech-to-text engine, a new wake word, another voice). See the Plugin Ecosystem to explore what's available, or the OVOS Repository Index for a map of every public repository in the project.

Explore by topic

Core Architecture

Understand the "brain" and "nervous system" of the platform:

Developer Resources

Ready to build your own plugins or skills?

Language Support

OVOS is built for a global community:

Who is behind OVOS?

OVOS is a community project supported by the OVOS Foundation (officially Stichting OVOS), a nonprofit registered in the Netherlands (Dutch Chamber of Commerce nr. 94609292, founded August 2024) that handles the project's legal and financial matters. Development happens in the open on GitHub. There is no commercial entity behind the project; day-to-day support is community-based — the OVOS Chat on Matrix for quick questions and the Open Conversational AI forum for longer discussions. For paid development or integration work, the community can connect you with experienced OVOS developers, including TigreGotico, the company of the lead OVOS/HiveMind developer. Vendors embedding OVOS should read Maturity and the project timeline to judge activity for themselves.

Help improve these docs

This manual is maintained by the OVOS community. Every page is cross-checked against the real source code. If you find an error or something unclear, please open a pull request or issue.