SteamOS Guide (2026): Flatpak, Distrobox, Developer Mode, SSH and Decky Loader

✅ Checked against Valve's SteamOS documentation and release notes · Last updated: 14 October 2026

SteamOS is Valve's Linux operating system for Steam hardware. It is built on Arch Linux, boots into a controller-friendly Gaming Mode, and includes a full KDE Plasma desktop called Desktop Mode. The current stable release is SteamOS 3.8.28, published on 25 September 2026, and SteamOS 3.9 is in the Beta and Preview channels. This SteamOS guide shows how to install apps with Flatpak, get a mutable Linux system with Distrobox, enable Developer Mode and SSH, add plugins with Decky Loader, and run non-Steam games with Proton. It also covers which devices Valve supports outside the Steam Deck.

SteamOS at a glance

Here is where SteamOS stands on 14 October 2026, taken from Valve's release notes and support pages.

Gaming Mode and Desktop Mode

Gaming Mode is what you see after boot: the Steam interface built for a gamepad. Desktop Mode is a standard KDE Plasma session where you install software, open a terminal (Konsole) and change system settings.

• Go to the desktop: press the STEAM button, open Power, then choose Switch to Desktop.
• Go back: double-click the Return to Gaming Mode shortcut on the desktop, or log off from the system menu.
• No keyboard or mouse: the right trackpad clicks as the primary button and the left trackpad as the secondary one. STEAM + X brings up the on-screen keyboard while Steam is running.

Since SteamOS 3.8, Desktop Mode runs on Wayland. Valve kept X11 as an option in the Steam developer settings and through the steamosctl tool, which helps if an older app misbehaves under Wayland. The same release added external HDR and VRR display support and per-display scaling to the desktop.

Where to install software on SteamOS

Use Flatpak for desktop apps, Distrobox for command-line tools and anything not on Flathub, and leave the system partition alone. The table shows why.

Install apps with Flatpak and Discover

SteamOS Flatpak support works out of the box: open Discover from the taskbar in Desktop Mode, search for an app and click Install. Valve's Desktop FAQ says Discover installs applications as Flatpaks on the writable part of the drive, so SteamOS updates do not break them. No password and no unlocking are needed.

If you prefer the terminal, open Konsole. These commands use the Flathub application IDs:

# See which remotes are configured
flatpak remotes

# Install apps from Flathub
flatpak install flathub org.videolan.VLC
flatpak install flathub org.mozilla.firefox
flatpak install flathub com.discordapp.Discord

# Run, list, update and remove
flatpak run org.videolan.VLC
flatpak list --app
flatpak update
flatpak uninstall org.videolan.VLC

# Delete runtimes nothing uses any more
flatpak uninstall --unused

Flatpak apps run in a sandbox. When one cannot see a folder you need, such as a game library on the microSD card, install Flatseal (com.github.tchx84.Flatseal) from Discover and give it the extra filesystem permission there. If you want to know how Flatpak differs from Snap and AppImage, read our Snap vs Flatpak vs AppImage comparison.

Launch a Flatpak app from Gaming Mode

Add the app to Steam as a non-Steam game. In Desktop Mode, open the Steam client, click "Add a Game" in the lower left corner, choose "Add a Non-Steam Game" and tick the app in the list. Back in Gaming Mode it appears in your library under the Non-Steam tab. You do not need to hunt for the binary path: the list already shows installed desktop apps.

Set a password so sudo works

The default user ships without a password. Valve calls this a secure default because it blocks SSH logins and stops anyone from running sudo. Anything that needs root (SSH, steamos-readonly, root containers) starts with setting one.

# In Konsole, as the default user
passwd

Pick a strong password: once SSH is on, it guards remote access too. SteamOS 3.8 also added a way to set the desktop password from the developer settings, if you would rather not use the terminal.

Enable Developer Mode

Turn it on in Gaming Mode under Settings > System > Enable Developer Mode. A new Settings > Developer section then appears. It holds the tools Valve gives game developers, such as pairing the device with the SteamOS Devkit Client on a PC. Valve's Steamworks docs explain that registering a device this way installs an SSH key on it and gives the PC full control for uploading and testing builds.

Developer Mode is not required to install apps. Valve's Steamworks FAQ confirms that Flatpak and other software install without it. You need it for things like the devkit tools, the X11 desktop session switch and other low-level options. In the 3.9 previews, the switch of the Wi-Fi backend to wpa_supplicant also sits in Developer Settings for existing installs.

Enable SSH on SteamOS

SSH needs two things: a password for the default user and a running OpenSSH server. SteamOS is Arch-based, and on Arch the server is the sshd.service systemd unit. Set the password first, then start the service and enable it at boot:

# 1. Set a password (skip if you already did)
passwd

# 2. Start the SSH server now and at every boot
sudo systemctl enable --now sshd

# 3. Check that it is running
systemctl status sshd

# 4. Find the device's IP address
ip addr

From another computer on the same network, connect with the user name and the IP you found. On a Steam Deck the user is deck:

ssh deck@192.168.1.50

Replace the address with your own. For daily use, switch to key-based login and turn password login off; our SSH setup guide with key authentication walks through it. Valve's own pages do not document sshd on SteamOS: they only state that the passwordless default blocks SSH. So if a future update changes the service, check the release notes first.

The read-only filesystem and steamos-readonly

The SteamOS system image is read-only, and each update replaces it. That is why Valve recommends Flatpak. Its Desktop FAQ is direct about the alternative: anything installed outside Flatpak, for example with pacman, may be wiped by the next SteamOS update.

If you still need to change the image, Valve documents this command:

sudo steamos-readonly disable

Valve calls this its "warning sandwich": only do it if you know what you are doing, and do not run random scripts from the internet with root rights. A container does the same job for most tools without touching the image, so try the next section first. A note for later: the 3.9 previews rename several steamos- scripts and packages to holo-, and Valve keeps aliases to the old names where appropriate.

Run any Linux distro with Distrobox

Distrobox runs a normal Ubuntu, Fedora or Arch userland in a container and wires it into your desktop: the container sees your home folder, the Wayland and X11 sockets, the network and USB drives, and you can export apps and commands to SteamOS. The Distrobox compatibility table says SteamOS has shipped Podman and Distrobox preinstalled since SteamOS 3.5, but those copies "are a little bit behind" upstream.

Check what you have first:

distrobox --version
podman --version

Install a newer Distrobox in your home folder

The project's Steam Deck guide installs Distrobox under ~/.local, where SteamOS updates do not touch it. Put that folder first in your PATH so your copy wins over the system one:

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | \
  sh -s -- --prefix ~/.local

Right now the script installs the stable 1.8.2.5 release by default. A rewrite in Go, Distrobox v2, is out as a release candidate (2.0.0-rc.4 in the install script), and you can get it with the --v2 flag. The developers still recommend v1 for regular use, and containers with exported apps must be recreated after moving to v2.

Create an Ubuntu container and export a tool

# Create and enter an Ubuntu 26.04 container
distrobox create --name ubuntu --image docker.io/library/ubuntu:26.04
distrobox enter ubuntu

# Inside the container: install with apt as usual
sudo apt update && sudo apt install -y neovim git ripgrep mpv

# Still inside: make nvim available on the SteamOS host
distrobox-export --bin /usr/bin/nvim --export-path ~/.local/bin

# Export a graphical app to the host's application menu
distrobox-export --app mpv

An exported binary is a small wrapper script that enters the container and runs the program, so nvim works from any SteamOS terminal. An exported app gets its own menu entry. To undo either, run the same export command with --delete.

Use an Arch container for the AUR

SteamOS itself is Arch, but you should not build AUR packages on the read-only image. An Arch container gives you pacman and an AUR helper without that risk:

distrobox create --name arch --image docker.io/library/archlinux:latest
distrobox enter arch

# Inside the container: install yay from the AUR
sudo pacman -S --needed git base-devel
git clone https://aur.archlinux.org/yay.git
cd yay
makepkg -si

Manage containers with distrobox list, distrobox stop arch and distrobox rm arch. If graphical apps from a container refuse to open, the Distrobox Steam Deck guide adds these lines to ~/.distroboxrc:

xhost +si:localuser:$USER >/dev/null
export PIPEWIRE_RUNTIME_DIR=/dev/null
export PATH=$HOME/.local/bin:$PATH

Install Decky Loader

Decky Loader is a community plugin launcher for Gaming Mode, made by the SteamDeckHomebrew team rather than Valve. The current release is v3.2.10 (4 October 2026). It installs from Desktop Mode, and its README says it works even if you never set a sudo password.

1. Switch to Desktop Mode and open a browser.
2. Download decky_installer.desktop from the Decky Loader GitHub page. Firefox may save it as decky_installer.desktop.download; rename it to remove .download.
3. Drag the file to the desktop and double-click it.
4. Type your password, or let the installer set the temporary password Decky!, which it removes when it finishes.
5. Pick Latest Release (the pre-release is for plugin developers).
6. Use the Return to Gaming Mode shortcut.

The fast way from Konsole, which asks for your password:

curl -L https://github.com/SteamDeckHomebrew/decky-installer/releases/latest/download/install_release.sh | sh

In Gaming Mode, press the Quick Access button (the "..." button on a Steam Deck), open the plug icon, then the store icon to browse plugins. On 14 October 2026 the official store listed 110 plugins. A few common ones, described from their store entries:

• PowerTools: turn CPU threads and SMT on or off, set CPU and GPU frequencies and GPU power limits, and cap the battery charge rate.
• CSS Loader: load community themes into the Steam interface.
• ProtonDB Badges: show ProtonDB ratings on game pages.
• SteamGridDB: change library artwork, handy for non-Steam games.
• HLTB for Deck: show How Long To Beat times.
• Storage Cleaner: find and clear shader cache and compatibility data.

To remove Decky, run the installer again and choose to uninstall, or use the uninstall one-liner from the README. Only install plugins from the store unless you trust the source; Decky lets you install from a URL, but its developers advise against untrusted sources.

Proton and non-Steam games

Proton is Valve's compatibility layer that runs Windows games on SteamOS, and it is built into Steam. Valve says the large majority of the Steam catalog runs this way (over 18,000 titles when it last counted). The latest tagged release in Valve's Proton repository is proton-11.0-2, from 21 August 2026.

Before buying, check the compatibility badge. Valve sorts games into four groups: Verified (works out of the box), Playable (needs some manual tweaking), Unsupported (does not work right now) and Unknown (not tested yet).

For stores outside Steam, install these Flatpaks:

# Epic Games Store, GOG and Amazon Games
flatpak install flathub com.heroicgameslauncher.hgl

# One launcher for games from many eras and systems
flatpak install flathub net.lutris.Lutris

# Install GE-Proton and other compatibility tools
flatpak install flathub net.davidotek.pupgui2

ProtonUp-Qt installs community builds such as GE-Proton for Steam, Lutris and Heroic. The newest GE-Proton on 14 October 2026 is GE-Proton11-9. To make a game use it, right-click the game in Steam, open Properties, and at the bottom of the Compatibility tab tick "Force the use of a specific Steam Play compatibility tool", then pick the version. After adding any of these launchers to Steam as a non-Steam game, they work from Gaming Mode too. For more on Proton outside SteamOS, see Linux for gaming: Steam, Proton and everything you need.

SteamOS outside the Steam Deck

Yes, SteamOS now runs officially on more than the Steam Deck. Valve's support page lists four devices as "Powered by SteamOS": Steam Deck, Steam Machine, Steam Frame and Lenovo Legion Go S. It lists a second group with beta support: the original Lenovo Legion Go, ASUS ROG Ally, ROG Ally X, other AMD-powered handhelds and AMD discrete GPUs. Valve adds that SteamOS can go on other AMD-powered devices as well, but Steam Support can only help a little with hardware outside the official list, and bugs should be reported on the SteamOS GitHub tracker.

Valve also sets expectations on its SteamOS page: users "should not consider SteamOS as a replacement for their desktop operating system". It is a gaming system first. Recent releases still add a lot for other hardware: SteamOS 3.8 added controller, TDP and speaker support for the ASUS ROG Xbox Ally series and controller and firmware update support for the Legion Go 2, and 3.8.28 added gamepad support for the MSI Claw 8 EX AI+, Konkr FIT and AYANEO Pocket S2.

Install SteamOS from a USB drive

The recovery image doubles as the installer. Valve's steps, in short:

1. Download the SteamOS image for Deck, Machine and PC from Valve's SteamOS download page. Steam Frame has its own image.
2. Write it to a USB drive of at least 8 GB: Rufus on Windows, Balena Etcher on macOS or Linux, or the command below on Linux.
3. On non-Valve hardware, disable Secure Boot in the firmware settings first.
4. Boot from the USB drive. The screen stays dark for a minute, then a desktop opens.
5. Choose Wipe Device & Install SteamOS. This erases the whole drive.

# Replace /dev/sdX with your USB drive; this erases it
bzcat steamdeck-recovery-4.img.bz2 | sudo dd if=/dev/stdin of=/dev/sdX oflag=sync status=progress bs=128M

The same USB environment offers three more options. Re-image Device is a full factory reset. Repair SteamOS reinstalls the system and tries to keep your games and files. Recovery tools opens a prompt for changes to the boot partition.

Updates, channels and rollback

Pick your update channel in Settings > System > System Update Channel. Stable is on 3.8.28. The Beta and Preview channels carry 3.9, which so far brings an updated Arch base, KDE Plasma 6.7.3, a kernel rebased on Linux 7.2, preliminary hibernation support (not yet in the Gaming Mode interface), wpa_supplicant as the default Wi-Fi backend for new installs, better support for running SteamOS as a virtual machine guest, and the steamos- to holo- rename.

The current stable release, 3.8.28, ships a new major Mesa driver with ray-tracing gains, much better VRAM management, the Linux 6.18.50 kernel, an option under Settings > Audio to reset all audio settings, and a fix for previous updates that failed to apply for some users.

If an update breaks something, SteamOS can boot the last working version and keep your games and saves. On a Steam Deck: hold the power button for 10 seconds to switch it off, hold the "..." button and press power, keep holding until the SteamOS menu appears, then choose the "Previous" entry. Valve's recovery page lists the button sequences for Steam Machine and Steam Frame. A full factory reset is in Settings > System > Factory Reset.

SteamOS vs Bazzite

Choose SteamOS if you own one of Valve's devices or a Legion Go S. Choose Bazzite if you want a similar gaming setup on ordinary PCs, handhelds, laptops and home theater PCs with broader hardware coverage. Both are image-based: Bazzite keeps the previous system image so you can boot it after a bad update, much like SteamOS does with its "Previous" entry.

If you prefer a regular Arch desktop with full pacman control, CachyOS is the performance-focused option, and Pika OS suits Windows switchers. Our Linux distros hub lists every distro we cover.

Troubleshooting and FAQ

What is the latest version of SteamOS?

SteamOS 3.8.28 is the latest stable release, published on 25 September 2026. SteamOS 3.9.2 is available in the Beta channel, and 3.9 previews have been out since late August 2026.

Can I install SteamOS on any PC?

You can install it on many AMD-based PCs, but only the Steam Deck, Steam Machine, Steam Frame and Lenovo Legion Go S are officially supported. The Legion Go, ROG Ally, ROG Ally X, other AMD handhelds and AMD discrete GPUs have beta support, and Steam Support has limited ability to help with other hardware.

Do Flatpak apps survive SteamOS updates?

Yes. Flatpaks install to the writable part of the drive, and Valve picked Flatpak because system updates do not break those apps. Software installed with pacman on the system image may be wiped by the next update.

Why does sudo ask for a password I never set?

The default user has no password, so sudo cannot work until you create one. Open Konsole in Desktop Mode and run passwd, or set it in the developer settings on SteamOS 3.8 or later.

SSH says connection refused. What should I check?

Check that the SSH server is running with systemctl status sshd and start it with sudo systemctl enable --now sshd. Also make sure the user has a password, because the passwordless default blocks SSH logins, and that both machines are on the same network.

My desktop app does not show up in Gaming Mode

Add it to Steam as a non-Steam game. In Desktop Mode open Steam, click "Add a Game", choose "Add a Non-Steam Game" and select the app; it then appears under the Non-Steam tab in Gaming Mode.

distrobox: command not found after an update

Your shell is not finding the copy in ~/.local/bin. Add export PATH=$HOME/.local/bin:$PATH to ~/.bashrc, run source ~/.bashrc, and reinstall Distrobox with the --prefix ~/.local script if the files are gone.

Decky Loader disappeared after a SteamOS update

Run the Decky installer again and install the stable release. The Decky README says this fixes most cases; if it does not, try the pre-release, then check the project's GitHub issues.

Decky Loader installs but the plugin menu never loads

Another program is probably using port 1337 or 8080, which Decky needs. Syncthing often takes 8080, and the Decky team suggests moving Syncthing to port 8384.

A SteamOS update broke my system. How do I roll back?

Boot the previous version from the SteamOS boot menu. On a Steam Deck, power off, hold the "..." button while pressing power until the SteamOS menu appears, and choose the "Previous" option; your games and saves are kept.

Do I need Developer Mode to install apps?

No. Flatpak apps, Distrobox containers and Decky Loader all install without it. Developer Mode adds the Developer settings section with devkit pairing and other low-level options.

Further reading

• Linux distros: the complete list we cover
• Bazzite Linux: the gaming distro for any PC
• Linux for gaming: Steam, Proton and everything you need
• CachyOS: the performance-tuned Arch Linux distro
• Arch Linux installation guide
• How to set up SSH on Linux with key authentication
• Snap vs Flatpak vs AppImage
• Vanilla OS 3: another immutable distro
• GNOME OS Preview: GNOME's own image-based system

Sources

• Valve: SteamOS page and FAQ
• Valve: SteamOS release notes (3.8, 3.8.28, 3.9 Previews, 3.9.2 Beta)
• Steam Support: Steam Deck and Steam Machine Desktop FAQ
• Steam Support: installing, re-imaging or repairing SteamOS
• Steam Support: SteamOS recovery and troubleshooting
• Steamworks: Developer Mode and devkit pairing
• Valve: Deck Verified categories
• Distrobox documentation and GitHub repository (compatibility table, Steam Deck guide, install script)
• Decky Loader README and releases and the Decky plugin store
• Flathub and the Flatpak documentation
• Valve: Proton repository and GE-Proton
• ArchWiki: OpenSSH (sshd.service)
• Bazzite

JM Carreira

I’ve used Linux since 2008 and it has been my main system since 2021. When an article has a “Tested on” box, I ran the steps on my Lenovo Tiny. More about me and the test machine.