# 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](../../releases/latest). 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.

```bash
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](https://jedisct1.github.io/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.

```bash
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](docs/features.md) — what Runi actually does
- [User flows](docs/user-flows.md) — end-to-end walkthroughs, from adding a
  game to launching it
- [Configuration schema](docs/config-schema.md) — every per-game and global
  setting, and the `--json` output contract

Per feature:

- [Launch providers](docs/launch-providers.md) — how a game is launched, and
  the three engines
- [Game identity](docs/game-identity.md) — the three identifiers, and why they
  are not interchangeable
- [OptiScaler](docs/optiscaler.md) — upscaler injection and provider selection
- [Lossless Scaling](docs/lossless-scaling.md) — frame generation, and
  installing the lsfg-vk layer
- [Native HDR](docs/hdr.md)
- [Controller support](docs/controller-support.md)
- [Technology Scan](docs/technology-scan.md)
- [Customize profiles](docs/customize-profiles.md)
- [Portable prefix bundles](docs/prefix-bundles.md)
- [Ubisoft Connect](docs/ubisoft-connect.md)

## License

Runi is free software under the **GNU General Public License, version 3 or
later**. The full text is in [LICENSE](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:

```bash
runi doctor
```