One toolkit for everything your Linux handheld was missing. A plugin platform for Linux gaming handhelds — an in-game overlay in Steam's Gaming Mode, a standalone app on the desktop. TypeScript end to end.
Loadout puts 20-plus plugins behind one controller-friendly UI: set your TDP and fan curve, check Proton compatibility before you install, launch your Epic library next to your Steam games, apply custom box art, install a recompiled N64 classic — without leaving your game. It runs as an in-game overlay in Steam's Gaming Mode and as a standalone app on the desktop, detecting which mode you're in and adapting automatically.
Install → · Featured plugins · All plugins · Supported devices · Docs
🚧 Pre-launch. Daily-driven on OneXPlayer devices and tested on Valve's Steam Deck. I'm looking for testers on other handhelds.
One command. It downloads the prebuilt binary and overlay, verifies SHA-256,
and installs the services. The backend installs as a system service (one
sudo prompt) so plugins can touch hardware without prompting again; the
overlay runs as your user:
curl -fsSL https://raw.githubusercontent.com/srsholmes/loadout/main/scripts/install.sh | shThen open it — as an overlay from Gaming Mode, or as a standalone app on the
desktop. On a keyboard, Ctrl+4 toggles it open and closed at any time
(controller shortcuts are in the FAQ). To remove it:
curl -fsSL https://raw.githubusercontent.com/srsholmes/loadout/main/scripts/uninstall.sh | shRequirements & install details
The installer downloads the prebuilt loadout binary + Electrobun overlay
into ~/.local/share/loadout/ and ~/.local/share/loadout-overlay/, verifies
SHA-256 against the release's SHA256SUMS, and writes the systemd units: a
system loadout.service (the backend, runs as root — hence the one-time
sudo) and a user loadout-overlay.service. See
docs/install-locations.md for exact paths.
Runtime requirements: an X11/Xwayland display, membership in the input group
(so the overlay can grab evdev devices), and a working Steam install. The CEF
libraries ship inside the overlay archive.
On SteamOS the installer additionally builds a small libwebkit2gtk-4.1
library closure (the overlay's native wrapper dlopens it) from a Fedora
container via podman — shipped in SteamOS Holo 3.7+ — the first time, then
caches it. This is kept out of the download on purpose so the release stays
small; Bazzite/CachyOS/Fedora already provide these libraries and skip the step
entirely.
To install or roll back to a specific version, set LOADOUT_VERSION to a
release tag:
LOADOUT_VERSION=v0.1.0 curl -fsSL https://raw.githubusercontent.com/srsholmes/loadout/main/scripts/install.sh | shIf this repository is private, the install command will 404 until it's made public;
install.shhonours aGITHUB_TOKENenv var for authenticated installs.
A few of the 20-plus. The screenshots are captured live from the running overlay, so they always match the current build.
Browse, install, and play recompiled retro games natively
Surface your Epic Games library as Steam shortcuts (GOG, Amazon, Ubisoft, xCloud planned)
Browse and apply custom game art (grids, heroes, logos, icons) from SteamGridDB
Browse, install, and toggle community CSS themes for Steam's Big Picture UI
Injects HowLongToBeat completion times into Steam library and store pages
Shows ProtonDB compatibility ratings for your Steam library — tier badges on every game tile, plus per-game detail in the home widget.
Track time spent playing games, including non-Steam games
Install and configure the LSFG-VK Vulkan frame generation layer
In Gaming Mode, some plugins reach into Steam's Big Picture UI directly — themed, badged, and native.
RecompHub turns recompiled classics into native Steam entries with full artwork — a dedicated collection in your library:
Theme Loader restyles the whole interface with community CSS themes:
The plugins that reach into Big Picture (badges, CSS theming) are Gaming-Mode-only by nature; everything else works in either mode.
Every plugin ships bundled with the release — nothing extra to download. Enable or disable each one from Settings → Plugins.
- Apex — OneXPlayer Apex device fixes: recover the internal gamepad when its xHCI controller dies on resume — manually or automatically on every wake (or blacklist the hid-oxp driver to prevent the drop-out), and block the fingerprint reader from waking the device on a light touch.
- Battery Tracker — Battery level, charge rate, estimated time remaining, and charge history
- Bluetooth — Quick connect/disconnect paired Bluetooth devices without leaving the game
- Disable Controller Input — Silence individual controllers by telling InputPlumber to drop their virtual targets — useful for handhelds where the built-in pad is hogging player 1
- Display Settings — Adjust display brightness and saturation
- Fan Control — Monitor and control fan speed, temperature, and fan curves — presets or a custom curve editor
- Flatpak Manager — Manage and update Flatpak applications without leaving your game
- HLTB — Injects HowLongToBeat completion times into Steam library and store pages
- InputPlumber — Install the InputPlumber input-routing daemon — no-op if a system package or a previous run already installed it
- Launch Options — Manage Steam game launch options and presets
- LSFG-VK — Install and configure the LSFG-VK Vulkan frame generation layer
- Network Info — Network information, WiFi details, and Cloudflare speed test
- PlayTime — Track time spent playing games, including non-Steam games
- ProtonDB Badges — Shows ProtonDB compatibility ratings for your Steam library — tier badges on every game tile, plus per-game detail in the home widget.
- Quick Links — Open YouTube guides, ProtonDB, wikis and more for the game you're playing
- RecompHub — Browse, install, and play recompiled retro games natively
- RGB Control — RGB LED control for Linux handhelds — supports OpenRGB, sysfs LEDs, and platform-specific interfaces
- Sound Loader — Browse, install, and toggle community UI sound packs from deckthemes.com
- SteamGridDB — Browse and apply custom game art (grids, heroes, logos, icons) from SteamGridDB
- Storage — Detect and mount a game-storage drive (e.g. a second SSD holding a Steam library) that the system stopped auto-mounting after an update, and optionally pin it in /etc/fstab so it survives future updates. Works on any device.
- Storage Cleaner — Shows disk usage, shader cache sizes, and lets users clean up space
- Store Bridge — Surface your Epic Games library as Steam shortcuts (GOG, Amazon, Ubisoft, xCloud planned)
- TDP Control — Adjust CPU/APU TDP wattage with presets and a slider
- Theme Loader — Browse, install, and toggle community CSS themes for Steam's Big Picture UI
- WiFi — Stop WiFi dropping out by disabling the radio's power saving. Writes a NetworkManager drop-in (and an iwd quirk where iwd is installed), applies it instantly, and re-asserts it on every wake. Cross-distro: SteamOS, Bazzite, CachyOS.
Loadout is Linux-only by design — it targets distros that ship Steam Gaming Mode. No Windows or macOS build.
| OS | Status |
|---|---|
| SteamOS (Steam Deck) | ✅ Supported |
| Bazzite | ✅ Supported |
| CachyOS | ✅ Supported |
Hardware tested so far:
| Device | Status |
|---|---|
| OneXPlayer APEX | ✅ Daily-driven |
| Steam Deck | ✅ Tested |
| OneXPlayer F1 Pro | ✅ Tested |
🙋 Got a different handheld? ROG Ally, Legion Go, OneXPlayer, GPD, AYANEO, AOKZOE — I'd love your help testing on other devices. Open an issue with your hardware and let's get Loadout running on it.
See docs/os-compatibility.md for per-distro notes (including the bundled-glibc caveat on stock SteamOS).
- TypeScript end to end. The plugin host, every plugin backend, every plugin UI, and the overlay itself run on Bun. A full plugin — backend + UI — is typically 150–300 lines.
- Our own overlay surface, not an injected panel. A standalone CEF window layered over Gamescope via X11 atoms — so Steam redesigns don't break it. The same window runs as the Desktop Mode app. Plugins can reach into Big Picture (badges, theming) via CEF's remote-debug protocol, but that's opt-in.
- Batteries-included SDK.
@loadout/uigives plugin authors typed RPC, themed React components, gamepad-aware spatial navigation, and persistent settings out of the box.
Built with Bun, Electrobun (CEF + Bun), React, Tailwind v4, and daisyUI. For the full picture, see docs/architecture.md and docs/plugin-development.md.
Build from source
git clone https://github.com/srsholmes/loadout
cd loadout
bun install
bun run build-and-install # compile + install to ~/.local/share/, enable servicesThe overlay ships a patched Electrobun native wrapper (see
apps/loadout-overlay/vendor/README.md)
that fixes a 100% CPU spin in CEF's browser process. build-and-install swaps
it in automatically; electrobun dev does not, so the dev-mode overlay runs
the stock wrapper and pins a CPU core. Build and install to see accurate
results:
bun run build-and-install # compile + install + enable services
systemctl --user restart loadout-overlay # restart the overlay to pick up the build
journalctl --user -u loadout-overlay -f # follow overlay logsCEF DevTools are at http://localhost:9222 (attach any Chromium or use CDP).
For fast UI iteration with hot reload, bun run dev:overlay starts the loader
dev server + Electrobun (stock wrapper — always confirm with build-and-install
before trusting a change). Full dev/build/test loop:
docs/plugin-development.md.
| Document | Description |
|---|---|
| Architecture | Loader architecture, plugin structure, startup sequence |
| Plugin Development | Plugin structure, backend/frontend APIs, examples |
| Steam UI Injection | Injectable surfaces, SteamClient API, Gamescope notes |
| Overlay / Gamescope | X11 atoms, input grab, display detection |
| Gamepad Navigation | Spatial navigation, focus management |
| OS Compatibility | SteamOS, Bazzite, CachyOS specifics |
| Releasing | Versioning policy + how releases are cut |
See CHANGELOG.md for the release history.
In Gaming Mode, trigger your configured wake shortcut on the controller to
bring up the overlay. On the desktop, launch Loadout like any other app and
it opens as a standalone window. In either mode, if you're on a keyboard (or
your controller shortcut isn't working yet), Ctrl+4 toggles it open and
closed at any time — handy as a fallback during first-time setup.
Yes — that's the main way. In Settings → Controller you can bind the overlay
to Guide + B or Guide + X. (Guide + A and Guide + Y are deliberately left
alone — Steam and InputPlumber reserve them for the QAM and Steam menu.) Ctrl+4
on a keyboard always works too, as a fallback.
First-time setup is much smoother with a keyboard attached. You'll be entering a few values (like a SteamGridDB API key) and configuring shortcuts, and typing those on a keyboard is far quicker than the on-screen keyboard. Once you're set up, day-to-day use is fully controller- and d-pad-friendly.
It's highly encouraged. The SteamGridDB plugin — and the custom artwork that other plugins pull in (box art, heroes, logos) — needs a free API key to fetch art. Grab one from steamgriddb.com/profile/preferences/api and paste it into the SteamGridDB plugin's settings; you only enter it once and it persists across reinstalls.
All 20-plus plugins ship bundled with the release — there's nothing extra to download. Enable or disable individual plugins from Settings → Plugins.
Re-run the same install command — it's idempotent. It pulls the latest release, checks for a newer binary and overlay, refreshes the bundled plugins, and leaves your config untouched:
curl -fsSL https://raw.githubusercontent.com/srsholmes/loadout/main/scripts/install.sh | shEverything — theme, UI scale, favourites, home dashboard layout, controller
shortcuts, and per-plugin state — lives in ~/.config/loadout/config.json
(honouring $XDG_CONFIG_HOME) and survives reinstalls and CEF profile wipes.
While the overlay is open, it exclusively grabs your controller so your inputs drive the overlay and don't leak through to the game underneath. That's by design — close the overlay and the controller returns to Steam immediately. If a pad stays unresponsive while the overlay is hidden, make sure you're on the latest version.
Backend logs are at ~/.config/loadout/logs/loadout.log, or follow them live:
journalctl -u loadout -f # backend (system service)
journalctl --user -u loadout-overlay -f # overlay (user service)Open an issue with your handheld, distro, and steps to reproduce — and if you're on an untested device, I'd love to hear from you.
curl -fsSL https://raw.githubusercontent.com/srsholmes/loadout/main/scripts/uninstall.sh | shLoadout stands on the shoulders of giants — the people and projects below made it possible. Please go star their work.
A huge thank-you to the Decky Loader community. Years of hard work on the Linux handheld homebrew ecosystem — and the incredible plugins built on top of it — paved the way for everything here and continue to inspire it. 💛
The platform is built on:
- Bun — the TypeScript runtime + single-binary compiler.
- Electrobun — CEF with Bun as the main process.
- React, Tailwind CSS, daisyUI — the UI stack.
- norigin-spatial-navigation — gamepad-friendly focus.
And many plugins are thin, grateful wrappers around brilliant upstream projects:
- SteamGridDB — community game artwork.
- ProtonDB — Proton compatibility ratings.
- HowLongToBeat — game-length data.
- legendary — the open-source Epic Games launcher behind Store Bridge.
- lsfg-vk & decky-lsfg-vk — Lossless Scaling frame generation as a Vulkan layer.
- RyzenAdj — TDP control.
- InputPlumber — input routing.
- OpenRGB — RGB LED control.
- DeckThemes & CSS Loader — community themes and UI sound packs.
- The N64/PC recompilation community (N64: Recompiled, OpenGOAL, and friends) behind RecompHub.
Built something Loadout relies on and not listed here? Open a PR — we want to credit you.
BSD 3-Clause — see LICENSE, NOTICE, and THIRD_PARTY_LICENSES.md.