CachyOS Gamescope Boot Wizard

A setup script that makes a CachyOS desktop install (running KDE Plasma + plasma-login-manager) always boot into a Steam Deck-style gamescope session - the same "always boots into Big Picture, switch to desktop and back on demand" experience SteamOS gives you on a real Deck or the Valve Steam Machine.

It exists because, as of the CachyOS March 2026 release (which switched the default login manager from SDDM to plasma-login-manager), the stock gamescope-session-cachyos tooling has a few gaps that stop this from working out of the box. This script patches around them.

What's actually broken (and what this fixes)

CachyOS's gamescope-session-cachyos package ships steamos-session-select, which is meant to work exactly like it does on real SteamOS. On a plasma-login-manager system, three things get in the way:

No User= written to the autologin config. steam-set-session (the script steamos-session-select calls under the hood) only ever writes a Session= key to the autologin config file. On SDDM this is fine, because SDDM's User= is set once by the installer and never touched again. plasma-login-manager needs both Session= and User= present to autologin at all - without User=, it just falls back to showing the greeter every boot.
Missing /etc/plasmalogin.conf.d directory. If that directory doesn't exist, steam-set-session fails outright when it tries to write to it. In practice this shows up as Steam's "Switch to Desktop" hanging forever on a "Switching to Desktop" message with no way back except a hard reset.
The base /etc/plasmalogin.conf wins over conf.d, and CachyOS ships it hardcoded to Session=plasma. Every CachyOS tool that changes sessions (steamos-session-select, Steam's power menu, and the cachyos-gamescope-autologin.service that's supposed to reset you back to gamescope after a desktop session) only ever writes to /etc/plasmalogin.conf.d/zz-steamos-autologin.conf. But the base /etc/plasmalogin.conf file takes priority over that fragment, and it ships with Session=plasma baked in - so none of those session switches ever actually stick, no matter what the fragment says.

This script fixes all three: it ensures the conf.d directory exists, sets the base config's Session=, User=, and Relogin=true correctly, and installs a small systemd path-watcher that keeps the base config in sync with whatever CachyOS's own tools write to the conf.d fragment - so switching sessions from inside Steam or the desktop actually works, in both directions, and resets to gamescope on the next boot by default (matching real Deck/SteamOS behavior).

It also optionally offers to install Valve's official Vapor KDE Plasma theme - the same colors, icons, wallpapers, and Plasma look-and-feel package used on real SteamOS - pulled directly from Valve's own SteamOS package mirror, so your desktop session matches the gamescope side visually.

Requirements

CachyOS (or an Arch-based system) with pacman
KDE Plasma installed
plasma-login-manager as the active display manager (the script will warn and ask for confirmation if it detects SDDM or something else instead - most of these workarounds are specific to plasma-login-manager)
A regular user account with sudo access

Usage

git clone <this-repo-url>
cd <this-repo>
chmod +x setup-gamescope-boot.sh
./setup-gamescope-boot.sh

Run it as your normal user, not as root - it calls sudo internally for the specific commands that need it.

The script will:

Ask which user account should autologin into gamescope (defaults to whoever's running the script).
Check for and offer to install gamescope-session-cachyos, steam, and mangohud if any are missing.
Create /etc/plasmalogin.conf.d if it doesn't exist.
Back up and rewrite /etc/plasmalogin.conf's [Autologin] section.
Remove any stray manual override files from earlier troubleshooting attempts (only files matching zzz-steamos-autologin*.conf - it never touches zz-steamos-autologin.conf, which CachyOS's own tools own).
Install a sync script (/usr/local/bin/sync-steamos-session.sh) and a systemd path unit that keeps the base config aligned with session switches made through Steam or steamos-session-select.
Ask whether you'd also like to install Valve's Vapor (Steam Deck) KDE theme. If you say yes, it downloads the official steamdeck-kde-presets package straight from Valve's SteamOS mirror and installs the color scheme, Plasma look-and-feel package, wallpapers, and icons into your user's ~/.local/share. This step only touches your home directory - nothing system-wide - and installing curl/zstd first if either is missing. Apply it afterwards from System Settings > Appearance > Global Theme > Vapor (Steam Deck) the next time you're in a Plasma session.

If you keep a folder named icons/ next to the script (e.g. custom Steam Deck logo assets), it'll also copy those into the right Plasma icon directories automatically. This is entirely optional - the theme installs fine without it.
Ask whether to reboot immediately to test the gamescope setup.

It's safe to re-run - every step checks current state first, and any file it modifies gets backed up once with a .bak-gamescope-wizard suffix before the first change.

After running it

Boot straight into gamescope: it should happen automatically. From inside gamescope, Steam's Power > Switch to Desktop should now work. From the desktop, logging out should drop you back into gamescope automatically (thanks to CachyOS's own cachyos-gamescope-autologin.service, which this script doesn't replace - it just makes sure the setting it writes actually takes effect).

You can also switch sessions manually at any time:

steamos-session-select gamescope   # switch to gamescope right now
steamos-session-select plasma      # switch to desktop right now
steamos-session-select persistent  # remember whichever session you used last, across reboots
steamos-session-select oneshot     # always start in gamescope regardless of what you used last (the default Deck-like behavior)

Restoring the originals

Every file the script modifies is backed up next to itself:

sudo cp /etc/plasmalogin.conf.bak-gamescope-wizard /etc/plasmalogin.conf

To fully remove the sync watcher this script adds:

sudo systemctl disable --now sync-steamos-session.path
sudo rm /etc/systemd/system/sync-steamos-session.path
sudo rm /etc/systemd/system/sync-steamos-session.service
sudo rm /usr/local/bin/sync-steamos-session.sh
sudo systemctl daemon-reload

Caveats

This works around current CachyOS/plasma-login-manager behavior as of September 2026. If CachyOS fixes steam-set-session upstream to write User= and to target whichever base config the login manager actually reads, this script becomes unnecessary - check for updates before running it on a freshly reinstalled system.
Tested on a Valve Steam Machine (desktop AMD APU + discrete GPU) running CachyOS Desktop edition. Should apply to any CachyOS desktop install using plasma-login-manager, but hasn't been tested on Steam Deck/Legion Go hardware, which typically ship with SDDM instead.
If you find CachyOS has patched the underlying issue, please open an issue or PR here so the script can detect that and skip the workaround.
The Vapor theme step depends on Valve's steamdeck-kde-presets package staying available at its current URL and version (steamdeck-kde-presets-0.29-1-any.pkg.tar.zst on steamdeck-packages.steamos.cloud). If Valve ships a newer version or changes the mirror layout, update pkg_ver near the top of install_vapor_theme() in the script.

CachyOS/gamescope-session#9 - "Switch to Desktop" hang due to missing /etc/plasmalogin.conf.d

License

MIT - do whatever you want with it.

8.0 KiB Raw Blame History