> For the complete documentation index, see [llms.txt](https://docs.kouch.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kouch.dev/docs/alpha.md).

# Kouch alpha — tester guide

Thanks for testing. Kouch is a couch frontend for emulators you already have: it shows your games, launches them with your own emulators, and hands up to 16 controllers to them (8 with motion) through Steam Input. It never downloads games, firmware or keys, and it never needs a driver.

This is an **alpha**: expect rough edges, and please report them (see the end).

## What you need

* Windows 10 or 11, or a Steam Deck (see "Steam Deck (early)"), with Steam running (Kouch reads controllers through Steam Input).
* Your own games in folders, and your own emulator(s) — or a Kouch emulator profile (`.kod`) that installs one from the emulator's own official releases.
* A controller. Keyboard and mouse work too (Settings › Controllers turns the keyboard into a player).

## Installing

Until Kouch is on Steam you get either the installer or a folder:

1. Run the installer, or unzip the folder anywhere. The installer puts Kouch in `%LOCALAPPDATA%\Programs\Kouch`. Earlier installers used `%LOCALAPPDATA%\Kouch`, which is also where Kouch keeps your library, saves and logs: installing this build removes the old program files from there (and nothing else) and installs to the new place. **Point your Steam shortcut at the new `Kouch.exe`** (in Steam: the shortcut's *Properties › Target*).
2. In Steam: *Games › Add a Non-Steam Game…* → pick `Kouch.exe`. **Start Kouch from Steam**: Steam Input (and motion) only reaches apps it starts.
3. Running Steam "as administrator" works too: everything Steam starts (Kouch and the emulators it launches) then runs as administrator, and Kouch mentions it once.
4. Your tester pack: drop `alpha-emulators.kod` on the Kouch window, choose *Take everything*, and Kouch installs each emulator in it for you, one after another. The pack covers Windows and the Deck (Linux): on each, Kouch installs that system's own build. Some emulators need your own system files: drop them onto the Kouch window (or use Settings › Emulators › Add system files…) and Kouch copies each one into the right emulator's folder after you confirm.

## First run

1. **Pick a disk.** Kouch creates an `Emulation` folder there (`roms`, `saves`, `bios`, `storage` …). If you already have one, keep "Use the existing Emulation folder" on — Kouch only adds what's missing and never touches your files.
2. **More disks** (optional), **Black or White**, then **emulators**: drop a `.kod` on the window or pick one. Kouch installs the emulator through its download queue and sets it up for your controllers.
3. Put games in `Emulation\roms\<system>\` (or add any folder in Settings › Paths) and press **Rescan**. Cover art is found automatically.

## Playing

* **Join:** press **A** on each controller on the connect screen (Players). Boxes pop in as players join; up to 8 on screen, 16 in total.
* **Launch:** pick a game → **Play**. The game page also has Options (per-game settings like resolution), Mods and Netplay.
* **Quick Menu in a game:** hold **Select + Start**. Players, motion, save/load state, screenshot, plugins, quit.
* **Quit:** from the Quick Menu. Kouch asks the emulator to close so it can save, and forces it only if it hangs.

## Try these

* **Themes:** Settings › Theme. Copy the sample `examples\themes\night-sky` into `%APPDATA%\kouch\themes\` and pick it. "New theme" gives you a folder to edit (`docs/THEME_FORMAT.md`).
* **Motion:** a pad with a gyro gets a motion slot automatically; tilt it in a game that uses motion.
* **Plugins:** Settings › Plugins (sample in `examples\plugins`). A plugin runs sealed off and only does what you allow.
* **Big libraries:** tested with 10,000 games; tell us if yours feels slow.

## Steam Deck (early)

Kouch runs on the Deck as an AppImage. It has run in Game Mode on a Deck OLED; treat it as early.

1. In Desktop Mode, put `Kouch-x86_64.AppImage` somewhere under your home folder (e.g. `~/Applications`) and make it executable (Properties › Permissions).
2. In Steam (still Desktop Mode): *Games › Add a Non-Steam Game…* → pick the AppImage. Then go back to Game Mode and start Kouch from your library. It opens full screen.
3. EmuDeck users: pick your existing `Emulation` folder in the first-run wizard, and Kouch uses it as it is. Emulators installed as Flatpaks or AppImages are supported; tell us if one does not start from Kouch.

**Known on the Deck:**

* The UI follows the screen's refresh rate (90 Hz on the OLED). Scrolling a big library still drops a few frames.
* The first start after an update takes a few seconds before the window appears.
* **Adding games to Steam's library in Game Mode** uses the Kouch Decky plugin (`kouch-decky.zip`, installed from Decky's developer settings › Install from ZIP). The in-app Settings › Plugins › Steam library works in Desktop Mode and on Windows.
* Keyboard and mouse as a player need no setup: Kouch reads them through the X server. *Advanced:* if keys don't reach Kouch while a game runs outside X (a Wayland-native emulator), `sudo usermod -aG input $USER` (then log out and back in) lets Kouch read keyboards and mice directly. It also lets any program you run read them, so only do it if you need it.

## Not in this alpha

* Workshop (themes, mods, plugins), Remote Play Together, Steam Cloud saves, rich presence and Steam's own *Join game* button need Kouch's own Steam app id; they show a note instead.
* **Works between testers already:** the friends list, lobbies, invites sent from inside Kouch, and netplay. They run under the id Kouch borrows until its own arrives.
* **Rumble in games:** Windows only, players 1 to 4. On the Steam Deck and Linux, games don't rumble yet.
* **Split-pair controllers** (a controller that comes apart into two halves) wait for a hardware check. Until then a pair works the way Steam presents it.
* An emulator in *exclusive* fullscreen may hide the Quick Menu — use borderless (the default in Kouch profiles).

## Reporting a problem

Tell us what you did, what you expected and what happened, and attach the report: **Settings › About › Create a report for the Kouch team**. It saves `kouch-report-<date>-<time>.zip` to your Desktop with the last 3 days of logs, your controllers, emulator versions and redacted settings. It never includes game names or paths, saves, firmware, keys or your Steam id. Add a screenshot if the problem is visual.

If Kouch won't start, send the log instead: `%LOCALAPPDATA%\kouch\logs\kouch.<date>.log`. Kouch sets aside any damaged settings file as `<name>.corrupt-<time>` and starts with defaults. The report includes those files once Kouch is running again.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kouch.dev/docs/alpha.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.