runi-dist/README.md

Runi

Windows gaming, native to Linux.

Runi launches Windows games under a chosen Proton build with per-game configuration, without requiring Steam — and owns the rest of the per-game contract too: runner management, gamescope/MangoHud, native HDR, controllers and Steam Input, upscalers, frame generation, artwork, logs, saves, notes and diagnostics.

This repository distributes Runi. It holds the released builds and the documentation you need to use them.

Install

Download runi.pyz from the latest release. It is a single self-contained file: no pip, no virtualenv, no terminal session to set anything up. It needs only Python 3.11 or newer, which every current Linux distribution and SteamOS already have.

chmod +x runi.pyz
mv runi.pyz ~/.local/bin/runi
runi --help

On a Steam Deck this is the whole install, and it never requires leaving Gaming Mode.

If you would rather install from source and have a terminal available, pipx install runi remains the recommended desktop route.

Verify what you downloaded

Every release is published with a SHA-256 and a minisign signature. They answer different questions, and the second is the one that matters most: the checksum tells you the download arrived intact, while the signature tells you it came from the key that signs Runi releases — which still means something if the server handing you the file is not the one you think it is.

sha256sum -c runi.pyz.sha256
minisign -Vm runi.pyz -p runi.pub

The public key is runi.pub, in this repository.

Documentation

Start here:

• Feature catalogue — what Runi actually does
• User flows — end-to-end walkthroughs, from adding a game to launching it
• Configuration schema — every per-game and global setting, and the --json output contract

Per feature:

• Launch providers — how a game is launched, and the three engines
• Game identity — the three identifiers, and why they are not interchangeable
• OptiScaler — upscaler injection and provider selection
• Lossless Scaling — frame generation, and installing the lsfg-vk layer
• Native HDR
• Controller support
• Technology Scan
• Customize profiles
• Portable prefix bundles
• Ubisoft Connect

License

Runi is free software under the GNU General Public License, version 3 or later. The full text is in LICENSE, and runi.pyz contains the complete corresponding source — it is a zip archive of the Python sources, so unzip runi.pyz gives you everything the GPL entitles you to.

Runi wraps third-party software it does not redistribute (Proton builds, umu-launcher, gamescope, MangoHud, OptiScaler, the lsfg-vk layer), each under its own terms, and never distributes Lossless.dll.

Reporting a problem

Runi ships a self-audit. Run it before reporting anything — it checks the registry against what is actually on disk, and often names the problem outright:

runi doctor