Goverlay: a Qt6 front end for MangoHud, vkBasalt and OptiScaler on Linux

What Goverlay actually removes from your workload

MangoHud, vkBasalt, vkSumi and OptiScaler are configured through plain text files and environment variables that have to reach the game process. Getting that right by hand means knowing where each tool looks for its config, which variables the Vulkan layer reads, and how to prefix a Steam launch option so the variables survive the Proton handoff. Goverlay is a Qt6 desktop application that edits those files for you through a card-based layout, then produces the launch command you paste into Steam or Lutris. The README describes the target audience plainly: Linux gamers who want performance monitoring, post-processing, upscaling and per-game environment overrides without editing configs by hand. It is a front end, not a runtime. MangoHud, vkBasalt, vkSumi and OptiScaler all have to be installed separately, and Goverlay only writes their configuration. The author describes himself as a network engineer who likes Linux and gaming, and states that the project exists on top of the work of the original maintainers of those core tools.

Game Mode, per-game config directories and the launch command box

The central design decision is per-game separation. When a game is selected, Goverlay switches to what the README calls Game Mode, and each game gets its own XDG-compliant config directory holding MangoHud.conf, vkBasalt.conf, vkSumi.conf, OptiScaler.ini, fakenvapi.ini, bgmod.conf and the bgmod wrapper binary. That layout is what makes per-title tuning practical: a competitive shooter can run a minimal overlay while a single-player title gets vkBasalt effects and an upscaler, and neither config overwrites the other. The bottom launch command box then updates to show the game-specific bgmod command with the %command% suffix, ready to paste into Steam. bgmod is a compiled Free Pascal binary rather than a shell script, and the README says it replaces the legacy fgmod approach. On launch it intercepts the game execution arguments, exports the environment variables from bgmod.conf, sets Wine DLL overrides, copies upscaler binaries and plugins into the game folder, and supports launcher EXE replacements plus UE Shipping EXE auto-discovery. It logs to /tmp/bgmod.log, to the game directory, and to ~/.local/share/goverlay/logs/[Game Name]/. A separate bgmod-uninstaller binary removes the wrapper files and restores the original backups.

Installing Goverlay and getting a first overlay on screen

The README recommends Flatpak as the universal method and points at Flathub for the application ID. Three commands cover the app and the Vulkan layers MangoHud and vkBasalt need; the README pins them to the 25.08 runtime branch.

flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak install flathub io.github.benjamimgois.goverlay
flatpak install flathub org.freedesktop.Platform.VulkanLayer.MangoHud//25.08 \
org.freedesktop.Platform.VulkanLayer.vkBasalt//25.08 -y

After that, run Goverlay from your application menu or with flatpak run io.github.benjamimgois.goverlay. The README notes that MangoHud must be installed for Goverlay to run, a requirement it dates to version 0.6.4. On Arch and derivatives the repository package is a single command, and the AUR package goverlay-git is the alternative.

sudo pacman -S goverlay

If you prefer no Flatpak runtime, the AppImage from the Releases page only needs the executable bit set.

chmod +x Goverlay_*.AppImage
./Goverlay_*.AppImage

In the interface, pick the game, adjust the MangoHud cards, and copy the command from the launch command box into the Steam launch options field. The README also documents PasCube, a Vulkan demo built from the PasVulkan engine that ships with Goverlay and launches on demand to preview your MangoHud, vkBasalt and vkSumi settings before you commit them to a game.

The Flatpak build hides host features on purpose

The most consequential limitation is stated in the README itself: inside Flatpak, Goverlay hides host-dependent features such as GameMode and Protontricks because it cannot reliably detect or execute host binaries. That is a sandbox boundary, not a bug, but it means the Flatpak and the native build are not feature-equivalent. If the GameMode tweak or Proton prefix management is the reason you wanted Goverlay, the Flatpak is the wrong package and you should look at the distribution build or the AppImage instead. The second limitation is the wrapper model. bgmod copies upscaler binaries and plugins into the game folder on every launch and can replace launcher executables. Anything that writes into a game directory is a candidate for interference with anti-cheat, with Steam's file verification, and with other mod managers doing the same thing. The README does not document rollback beyond the bgmod-uninstaller binary, and it does not describe how bgmod behaves when a game updates and overwrites the files it placed. Treat a game with kernel-level anti-cheat as out of scope until you have read the logs from a test launch.

How Goverlay differs from editing MangoHud.conf yourself

The obvious alternative is not another GUI but the config files themselves. MangoHud reads a MangoHud.conf, and a per-game setup can be done with a file next to the game or with environment variables in the Steam launch options. That approach has no extra binary in the launch path, works on any distribution, and is trivial to keep in version control. What it does not give you is discovery: Goverlay surfaces the available MangoHud options as cards, which is how most people learn what the overlay can do, and it coordinates several tools that each have their own config format. The trade is transparency for convenience. A hand-written launch option is a string you can read and reason about; a bgmod wrapper is a compiled binary that exports variables, sets DLL overrides and copies files, and the README's description of that pipeline is the only documentation of it. If you already know which MangoHud keys you want, the manual route is less machinery.

Install channels, maintenance and the GPL-3.0 licence

Goverlay is licensed GPL-3.0, which matters for anyone who wants to bundle it: distributing a modified binary carries source obligations, and the repository ships the full Pascal sources and Lazarus project files, so the source is available to satisfy them. The build is driven by a Makefile whose default target builds goverlay, start_goverlay.sh, bgmod, bgmod-uninstaller, pascube and bgmod-splash, with lazbuild invoked with the Qt6 widgetset. That means a source build needs the Lazarus IDE with Qt6 support, the Qt6 development libraries, make and git, plus qt6pas, which the README notes is missing from some distributions and points at David Bannon's libqt6pas releases for a .deb. The README explicitly warns that Fedora, Debian and Ubuntu repositories often ship outdated versions and recommends Flatpak or AppImage there. On maintenance cost: the last push to the repository was on 2026-08-29, and the most recent releases are 1.9.0 from 2026-08-22 and 1.8.11 from 2026-08-05, alongside a nightly build. The upgrade path that costs least is the Flatpak, because the application and the Vulkan layers are updated by flatpak update rather than by a distribution release cycle.

Who should adopt it, and what to check first

Goverlay fits a Linux gamer on Steam or Lutris who wants MangoHud running with a few toggles and does not want to learn the config syntax first. It fits less well if you already keep your MangoHud.conf in a dotfiles repository, because the generated per-game directories become a second source of truth you have to reconcile. The Flatpak is the safest first install and the one the README recommends for Fedora, Debian and Ubuntu. Verify three things before you rely on it: that MangoHud is present, since Goverlay will not start without it; that the launch command box produced a bgmod command and not a stale one after you switched games; and that /tmp/bgmod.log plus the per-game log under ~/.local/share/goverlay/logs show the environment variables you expected. If you are on a distribution where the packaged version lags, install from Flathub rather than the repository, and remember that GameMode and Protontricks are hidden in that build.

Editorial conclusion

Adopt Goverlay if you run MangoHud, vkBasalt or OptiScaler on Linux and want per-game configs generated for you; the Flatpak on Flathub is the version to start with, since the README warns that Fedora, Debian and Ubuntu repositories ship outdated builds. Skip it if you already maintain your configs in version control and do not want a wrapper binary copying files into game directories. Before trusting it on a game you care about, read /tmp/bgmod.log and the per-game log under ~/.local/share/goverlay/logs after one launch, and check that bgmod-uninstaller restored your original executables.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes