Skip to content

Install the Open Voice OS GUI

For Linux eyes only

The GUI is currently available only on Linux operating system, not on Mac OS or Windows.

The Open Voice OS GUI supports two types of system execution:

  • Using X or Wayland display servers
  • Using EGLFS which doesn't require any display server which is perfect for headless installation

When using EGLFS, the DISPLAY variable from the .env composition environment file must be removed or commented as if present the X or Wayland display servers will be tried first and result in an ovos_gui container in error.

Hardware accelerated on Raspberry Pi 4 and 5

Raspberry Pi 4 and 5 will leverage the GPU hardware acceleration which will provide a smoother experience.

If not running on a Raspberry Pi 4 or 5 then the CPU might be used to render the GUI which will result in a high CPU consumption and a poor user exprience.

EGLFS on Raspberry Pi 5

The Raspberry Pi 5 board doesn't use /dev/dri/card0 by default anymore for the GPU rendering. The solution to this issue is to create an EGLFS configuration referencing the right card to use.

  "device": "/dev/dri/card1",
  "hwcursor": false

The QT_QPA_EGLFS_INTEGRATION variable must be set to eglfs_ksm and QT_QPA_EGLFS_KMS_CONFIG variable must be set to /home/$OVOS_USER/.config/mycroft/ovos-eglfs.json in the .env file.

Please check the composition environment file section for more details.


The ovos-gui-messagebus component must be configured in order to receive the QML files from the skill containers. Because of these file transfers, the ovos-message-bus component must be configured to allow bigger payload.

  "logs": {
    "path": "stdout"
  "play_wav_cmdline": "aplay %1",
  "lang": "en-us",
  "listener": {
    "VAD": {
      "module": "ovos-vad-plugin-silero"
  "gui": {
    "extension": "ovos-gui-plugin-shell-companion",
    "gui_file_host_path": "/home/ovos/.cache/gui_files"
  "websocket": {
    "max_msg_size": 100

xhost and display servers


You can skip this section if your are using EGLFS and go to GUI services deployment.

In order to allow only the ovos_gui container to access to the X or Wayland display server, you will have to allow the container (based on its hostname) to connect to the display session.

export DISPLAY=":0"
xhost +local:ovos_gui

This command is not permanent, when your operating system will reboot you will have to run the command again. To make it permanent systemd should be leveraged as a user service.

mkdir -p ~/.config/systemd/user
mkdir -p ~/.config/systemd/user

Create the xhost.service unit file into the ~/.config/systemd/user directory.

Description=Allow ovos_gui container to use X from user session

ExecStart=/usr/bin/xhost +local:ovos_gui
ExecStop=/usr/bin/xhost -local:ovos_gui


Enable and start the new xhost.service systemd service.

systemctl --user enable xhost.service
systemctl --user start xhost.service
systemctl --user enable xhost.service
systemctl --user start xhost.service

The xhost command is part of the x11-xserver-utils package on Debian based distributions such as Raspberry Pi OS.

GUI services deployment

Podman users 💪

If you are running Podman instead of Docker, replace docker compose with podman-compose.

docker compose --project-name ovos --file docker-compose.yml --file docker-compose.raspberrypi.yml --file docker-compose.skills.yml --file docker-compose.gui.yml --file docker-compose.raspberrypi.gui.yml up --detach
docker compose --project-name ovos --file docker-compose.yml --file docker-compose.skills.yml --file docker-compose.gui.yml up --detach