Images¶
Pre-built images
The compose bundles in compose/ reference images hosted on Docker Hub
under docker.io/smartgic. The same images, with the same tags and
digests, are also published to ghcr.io/openvoiceos/ovos-docker (for
example ghcr.io/openvoiceos/ovos-docker/ovos-core:alpha), a mirror
without pull-rate limits;
point the image: references of your compose files there if Docker Hub
rate-limits you. Buildx Bake defaults to docker.io/smartgic; if you
publish to a different registry, update the image: references in your
compose files.
Open Voice OS is a sophisticated piece of software which has several components. These components have been split into containers to provide better isolation and a microservice approach.
GUI images
The ovos-gui-shell and ovos-gui-original images are no longer built or
supported; the last published tags remain on the registries but receive no
updates.
The GUI container images are larger than the other images as they need many QT libraries and GStreamer plugins in order to provide all the features supported by the voice assistant.
Supported CPU architectures¶
Container images can be used for different CPU architectures using the multi-platform images feature.
| CPU architecture | Description |
|---|---|
amd64 |
Such as AMD and Intel processors |
arm64 |
Such as Raspberry Pi 64-bit SoC |
armv7l |
Such as Raspberry Pi 32-bit SoC (not supported because of onnxruntime1) |
Containers¶
The list below is not exhaustive and doesn't mention anything about skill containers, but it is a fair list of the main components currently supported in ovos-docker.
| Container | Description |
|---|---|
ovos_messagebus |
Read more about ovos-messagebus |
ovos_phal |
Read more about ovos-phal |
ovos_phal_admin |
Read more about ovos-phal admin variant |
ovos_audio |
Read more about ovos-audio |
ovos_listener |
Read more about ovos-listener |
ovos_core |
Read more about ovos-core |
ovos_cli |
Read more about ovos-cli |
ovos_gui_websocket |
Read more about ovos-gui-websocket |
Tags¶
Container image tags select which release channel of Open Voice OS you deploy: bleeding-edge alpha packages, stable versions selected for testing, or the stable set.
| Image tag | Description |
|---|---|
alpha |
Built from constraints-alpha.txt of ovos-releases: alpha releases from PyPI, rebuilt automatically when the constraints change |
testing |
Built from constraints-testing.txt: stable versions selected for testing (the installer's default channel) |
stable |
Built from constraints-stable.txt |
latest |
Always the same image as stable |
<channel>-YYYYMMDD |
Immutable copy of a channel tag as published on that day, for rollbacks |
<channel>-amd64, <channel>-arm64 |
Single-architecture images the build pipeline publishes before merging them; not meant to be pulled directly |
Tag availability
Tag availability depends on what has been published to the registry. Check the registry if you need a specific version.
Stable alias
When building locally, TAG=stable also tags LATEST_TAG (default
latest). Override LATEST_TAG if you want a different alias.
What is inside¶
All Python images share one base (ovos-base, Debian slim with Python 3.13,
a virtual environment and a pinned uv);
services needing sound add ovos-sound-base, skills add ovos-skill-base.
Every channel tag is a multi-architecture manifest list (amd64 + arm64)
carrying an SBOM and SLSA provenance attestation, signed with cosign, published
to both docker.io/smartgic and ghcr.io/openvoiceos/ovos-docker with
identical digests,
and labelled with:
| Label | Content |
|---|---|
org.opencontainers.image.revision |
ovos-docker commit the image was built from |
io.openvoiceos.constraints.ref |
ovos-releases commit whose constraints-<channel>.txt pinned the packages |
org.opencontainers.image.created |
Build time |
Verify a signature with:
cosign verify docker.io/smartgic/ovos-core:stable \
--certificate-identity-regexp 'https://github.com/OpenVoiceOS/ovos-docker/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
Build images locally¶
If you need a private registry, custom tags, or local builds, use Docker Buildx Bake from the source repository:
./scripts/bake.sh --load --no-push
TAG=alpha CHANNEL=alpha VERSION=alpha PLATFORMS=linux/amd64,linux/arm64 ./scripts/bake.sh
./scripts/bake.sh -T skills
Builds require Docker with Buildx (BuildKit). Podman works for running images, but builds use Docker Buildx Bake.
For a full list of targets and build variables, see Build images.
--load forces linux/amd64 and cannot load multi-arch manifests locally.
Multi-arch builds may require binfmt/qemu; set ENSURE_BINFMT=true or use
--ensure-binfmt.
Volumes¶
To allow data persistence, Docker or Podman volumes are required. They will prevent downloading the requirements every time the containers are re-created.
| Volume | Description |
|---|---|
ovos_gui_files |
Share QML files from skills between the GUI websocket service and the GUI client |
ovos_listener_records |
Wake words and utterances recorded samples |
ovos_local_state |
Mostly used to store logs from the different components |
ovos_models |
Models downloaded by precise-lite wake word plugin |
ovos_nltk |
Punkt Python package required by NLTK |
ovos_tts_cache |
.wav and .pho files acting as cache from TTS transcription |
ovos_vosk |
Models downloaded by VOSK during the initial boot |
ovos_listener_records allows you to store samples of wake words and utterances which could help you to build or improve models.
Enable samples recording
By default the recording features are disabled, "record_wake_words": true and "save_utterances": true will have to be added to the listener section of mycroft.conf to enable these capabilities.
But first thing's first you need to have Open Voice OS's containers up and running. Follow the guide.