App reference

Pre-alpha software

Back up your existing emulator setup before the first run. On the first run, Kyaraben can overwrite emulator configurations and the saves in emulator directories. For best results, start with no emulators installed. Report issues on GitHub.

Selecting systems and emulators

The main screen shows all available systems and their emulators. Check a system to enable it. Uncheck it to disable it.

Checking BIOS and firmware status

Some systems require BIOS or firmware files. Kyaraben does not distribute these files. For each file, the provisions panel shows if the system needs it, if Kyaraben found it, and if it passes hash verification.

Emulator support

Kyaraben configures paths, controller bindings, and hotkeys for each emulator. Not all emulators support all features. This table shows what Kyaraben configures for each emulator.

Emulator	System	Syncs	Hotkeys	Resume	Controller	Players	Provisions
Snes9x	SNES	saves, states, screenshots	full	full	configured	4	none
bsnes	SNES	saves, states, screenshots	full	full	configured	4	none
Mesen	NES	saves, states, screenshots	full	full	configured	4	none
Genesis Plus GX	Genesis, SMS, GG	saves, states, screenshots	full	full	configured	4	none
mGBA	GB, GBC, GBA	saves, states, screenshots	full	full	configured	4	none
melonDS	DS	saves, states, screenshots	full	full	configured	4	none
Citra	3DS	saves, states, screenshots	full	full	configured	4	none
Azahar	3DS	saves, states, screenshots	full	full	configured	4	none
Mupen64Plus	N64	saves, states, screenshots	full	full	configured	4	none
Beetle Saturn	Saturn	saves, states, screenshots	full	full	configured	4	Saturn BIOS
Beetle PCE	PC Engine	saves, states, screenshots	full	full	configured	4	CD System Card (for CD games)
Beetle NGP	Neo Geo Pocket	saves, states, screenshots	full	full	configured	4	none
FBNeo	Arcade	saves, states, screenshots	full	full	configured	4	varies by game (optional)
FBNeo	Neo Geo	saves, states, screenshots	full	full	configured	4	Neo Geo BIOS (optional)
Stella	Atari 2600	saves, states, screenshots	full	full	configured	4	none
VICE x64sc	C64	saves, states, screenshots	full	full	configured	4	none
DuckStation	PSX	saves, states, screenshots	full	save	configured	4	PSX BIOS
PCSX2	PS2	saves, states, screenshots	full	save	configured	4	PS2 BIOS
PPSSPP	PSP	saves, states, screenshots	full	load	configured	1	none
Dolphin	GC, Wii	saves, states, screenshots	full	none	configured	4	Wii keys (optional)
Flycast	Dreamcast	saves, states, screenshots	partial	full	configured	1	DC BIOS (optional)
Cemu	Wii U	saves	none	none	configured	1	Wii U keys (optional)
Eden	Switch	saves, screenshots	partial	none	configured	2	Switch keys
xemu	Xbox	states, screenshots	none	none	auto	4	Xbox Boot ROM, Flash ROM
Xenia Edge	Xbox 360	saves, screenshots	none	none	auto	-	none
Vita3K	PS Vita	saves, screenshots	none	none	auto	-	PS Vita firmware
RPCS3	PS3	saves, states, screenshots	none	none	auto	-	PS3 firmware

Columns:

• Syncs: the data in the collection that can synchronize. saves are in-game saves, states are savestates, and screenshots are captured screenshots.
• Hotkeys: full is save state, load state, fast forward, pause, screenshot, and quit. partial is some of these. none means that Kyaraben configures no hotkeys.
• Resume: full is autosave on exit and autoload on launch. save is autosave only. load is autoload only. none means no resume support.
• Controller: configured means that Kyaraben generates the controller bindings. auto means that the emulator detects the controller.
• Players: the number of controller slots that Kyaraben configures. - means that the emulator sets the slots.
• Provisions: the BIOS, firmware, or encryption keys that the emulator needs. Items marked “(optional)” add features, but games run without them.

The RetroArch cores (bsnes through VICE x64sc) share one configuration. They use the RetroArch hotkey system: hold Back (Select) and push a second button.

Applying changes

Click apply. If the changes conflict with your existing configuration, Kyaraben shows a preflight check first. The check lists each config file that Kyaraben creates, modifies, or leaves unchanged, with line-by-line diffs.

When you confirm, Kyaraben:

1. Downloads emulator packages from a binary cache
2. Installs emulator binaries to Kyaraben-managed directories
3. Generates or updates emulator configuration files
4. Creates the folder structure in your Collection
5. Creates .desktop entries for each emulator
6. Updates the manifest, which records what Kyaraben installed

Kyaraben updates the manifest only after all steps succeed. If apply fails, the previous state stays intact.

Browsing and launching games

To browse and launch your games, enable EmulationStation DE in the settings. EmulationStation DE scans your ROM directories. It gives one game launcher with metadata scraping, media art, and controller navigation.

EmulationStation DE shows all systems with ROMs

EmulationStation DE shows every system that has ROMs in your collection, also systems that you did not enable in Kyaraben. Kyaraben configures emulators only for the systems that you enable. Games for other systems show in the list, but they do not launch correctly.

What Kyaraben installs and where

Kyaraben installs emulators and tools into its own directories:

• Emulator binaries: ~/.local/state/kyaraben/
• Desktop entries: ~/.local/share/applications/kyaraben/
• CLI tools: ~/.local/bin/kyaraben, ~/.local/bin/kyaraben-ui

Kyaraben does not overwrite emulators that you install from other sources. But these emulators share the config files at the default paths, for example ~/.config/retroarch/retroarch.cfg.

Kyaraben does not manage the files that emulators create, such as shader caches, input profiles, and logs.

Configuration management

Kyaraben manages specific keys in emulator config files: the paths into your Collection , such as ROM, BIOS, and save directories. You can also let Kyaraben manage some settings, such as shaders and auto-resume. You configure all other settings, such as resolution and audio.

On apply, Kyaraben compares the file on disk with the version that it wrote last. Kyaraben keeps your changes to keys that it does not manage. If you changed a managed key, Kyaraben warns you before it overwrites the key.

Do not use another tool that writes to the same config files. The two tools will conflict.

The collection

See collection reference for the folder structure, what syncs, and file versioning behavior.

Guarantees

• Installations are reproducible. The same config gives the same result on any Linux machine.
• Kyaraben needs no root access and does not modify system packages. Its binaries and state are in ~/.local/state/kyaraben/ and ~/.config/kyaraben/. Emulator configs go to their default paths, for example ~/.config/retroarch/.
• ~/.local/bin/ puts kyaraben and kyaraben-ui on your PATH. Kyaraben creates .desktop entries for itself and for each installed emulator. These entries use the paths that Kyaraben manages.
• Apply is atomic. If it fails, Kyaraben does not update the manifest, and the previous state stays intact.
• Apply is idempotent. Two runs with the same config give the same result.
• Uninstall is clean. kyaraben uninstall removes only the files that Kyaraben manages. It never touches your collection (ROMs, saves, BIOS).

Updating

Kyaraben checks for updates shortly after startup. If a new version is available, a banner lets you download and install it. To check manually, click the settings icon in the sidebar.

After an update, run Apply to get the new emulator configurations in the update. Kyaraben asks you to do this, but it is optional.

Hotkeys

Kyaraben configures controller hotkeys for the emulators that support them. Hold the modifier button (Back/Select on most controllers) and push an action button.

Action	RetroArch cores	DuckStation	PCSX2
Save state	Select + R1	Select + R1	Select + R1
Load state	Select + L1	Select + L1	Select + L1
Next slot	Select + D-Pad Right	Select + D-Pad Right	Select + D-Pad Right
Previous slot	Select + D-Pad Left	Select + D-Pad Left	Select + D-Pad Left
Fast forward	Select + R2	Select + R2	Select + R2
Pause	Select + A/Cross	Select + A/Cross	Select + A/Cross
Screenshot	Select + B/Circle	Select + B/Circle	Select + B/Circle
Quit	Select + Start	Select + Start	Select + Start
Open menu	Select + Y/Square	Select + Y/Square	-

Kyaraben configures no hotkeys for the emulators with none in the emulator support table. Use their keyboard shortcuts, or configure hotkeys manually.

Troubleshooting

Game won’t launch

If a game does not launch or shows a black screen:

1. Check the BIOS files. Run kyaraben doctor, or look at the provisions panel in the UI. Many systems require specific BIOS versions.
2. Check the ROM format. Some emulators support only some formats. For example, PCSX2 works best with .iso or .chd files, not .bin/.cue.
3. Read the emulator logs. Emulators write logs to their config directories, for example ~/.config/duckstation/.

Controller not detected

Kyaraben uses SDL2 for controller input. If your controller is not detected:

1. Make sure that the controller works in other applications.
2. For a Bluetooth controller, pair and connect it before you start the emulator.
3. On Steam Deck in Desktop Mode, Steam Input can block the controller. Disable Steam Input for the emulator.

Non-goals

• Windows, macOS, iOS, or Android support
• ROM management or scraping (use EmulationStation DE)
• Netplay configuration

Privacy and network activity

Kyaraben collects no telemetry or analytics. It makes network requests only in these cases:

• Update checks: on startup, Kyaraben fetches https://api.github.com/repos/fnune/kyaraben/releases/latest. GitHub sees your IP address and the kyaraben-updater user agent.
• Emulator downloads: on apply, Kyaraben downloads emulator packages from their official sources (GitHub releases, GitLab, libretro buildbot).
• Synchronization: if you enable sync, Kyaraben connects to a relay server to pair devices. Syncthing then transfers files peer-to-peer.

The relay server keeps a pairing code until a device uses it or it expires. It logs device identifiers and IP addresses only as necessary for the pairing handshake.

Synchronization

Kyaraben synchronizes your saves, states, screenshots, and scraped metadata across all your devices. For example, start a game on your desktop and continue it on your Steam Deck.

Synchronization is peer-to-peer and needs no cloud account. Kyaraben installs Syncthing when you enable synchronization. Data goes directly between devices that are online. Changes wait in a queue while a device is offline.

Synchronization requires systemd. Kyaraben manages the service with systemctl --user.

Enabling synchronization

Go to Settings > Synchronization and click “Enable synchronization”.

Pairing devices

Pair two devices to synchronize them. The devices do not need to be on the same network.

On the first device:

1. Go to Settings > Synchronization
2. Click “Generate pairing code”
3. A 6-character code appears (e.g. K7X9M2)

On the second device:

1. Go to Settings > Synchronization
2. Enter the code from the first device
3. Click “Connect”

See collection reference for what syncs and file versioning behavior.

Managing synchronization

To add a new device, see Pairing devices.

To remove a device, click the trash icon next to it in the synchronization settings.

To manage synchronization from the command line, see the CLI reference.