RetroDECK-SteamAppRunner

Launch Steam apps from RetroDECK, either as individual games or as emulators. This project is experimental. Designed for SteamOS-like distributions, it runs as a user-level systemd service that exposes an HTTP endpoint for launching Steam apps.

Requirements

• Python 3
• steam available on PATH
• systemd user session

Install

From this repository directory:

bash install.sh

Check that the service is running:

systemctl --user status retrodeck-steamapprunner.service

Uninstall

bash uninstall.sh

Configuration

The service listens on localhost only, on port 8765 (configured in the systemd unit).

To change the port, edit Environment=PORT=8765 in ~/.config/systemd/user/retrodeck-steamapprunner.service, then:

systemctl --user daemon-reload
systemctl --user restart retrodeck-steamapprunner.service

Usage

Launch a Steam app as an emulator

1. Make sure RetroDECK-SteamAppRunner is installed.

2. Add your emulator to Steam via Add a Game.

3. Right-click the Steam app, then go to Manage > Add Desktop Shortcut.

4. Open your RetroDECK custom systems file in an editor:

   1. By default: /home/deck/retrodeck/ES-DE/custom_systems/es_systems.xml
   2. Add an entry for the emulator system you want to use.
   3. Under <command>, set the path to the Steam app's .desktop shortcut.
   4. Example for Xenia Edge:

   <system>
     <name>xbox360</name>
     <fullname>Microsoft Xbox 360</fullname>
     <path>%ROMPATH%/xbox360</path>
     <extension>. .desktop .iso .ISO .sh .xex .XEX .zar .ZAR</extension>
     <command label="Xenia Edge Steam Shortcut">curl -X POST "http://localhost:8765/launch-steam-app" -H "Content-Type: application/json" --data '{"shortcut":"/home/deck/Desktop/Xenia Edge Windows.desktop","rom_path":"%ROM%","close_rd":false}'</command>
     <platform>xbox360</platform>
     <theme>xbox360</theme>
   </system>

5. Right-click the app in Steam again, then go to Properties > Launch Options:

   1. The ROM being launched is written to /tmp/retrodeck-steamapprunner/rom_path.
   2. Configure the Steam app to pass that ROM path to the emulator. This depends on the emulator's launch arguments, but in most cases:
      1. If the field is empty, enter: $(cat /tmp/retrodeck-steamapprunner/rom_path)
      2. If the field already has content, append $(cat /tmp/retrodeck-steamapprunner/rom_path) with a space before it.

6. After adding ROMs to the new system in RetroDECK, you should be able to launch them through the Steam emulator you configured.

Launch Steam apps as individual games

1. Right-click the Steam game, then go to Manage > Add Desktop Shortcut.

2. Go to your RetroDECK ROMs folder:

   1. By default: /home/deck/retrodeck/roms/
   2. Create a new steam folder if it does not exist.

3. Move the desktop shortcut into the steam folder.

4. Open your RetroDECK custom systems file in an editor:

   1. By default: /home/deck/retrodeck/ES-DE/custom_systems/es_systems.xml
   2. Add the following system:

   <system>
     <name>steam</name>
     <fullname>Valve Steam</fullname>
     <path>%ROMPATH%/steam</path>
     <extension>.desktop .sh</extension>
     <command label="Steam Shortcut">curl -X POST "http://localhost:8765/launch-steam-app" -H "Content-Type: application/json" --data '{"shortcut":"%ROM%","close_rd":false}'</command>
     <platform>steam</platform>
     <theme>steam</theme>
   </system>

5. You should now be able to launch the Steam game from RetroDECK under the Steam system.

Performance impact

1. With the setup above, RetroDECK stays running while the launched emulator or game is active.
2. This can affect performance depending on the game.
3. Set close_rd to true to close RetroDECK before launching, which avoids that overhead.

Endpoint

POST http://localhost:8765/launch-steam-app

All parameters must be sent as a JSON request body. Query parameters are not allowed.

Field	Required	Description
shortcut	yes	Path to the Steam .desktop shortcut to launch
rom_path	no	Path written to /tmp/retrodeck-steamapprunner/rom_path (cleared after 10 seconds)
close_rd	no	If true, closes RetroDECK (net.retrodeck.retrodeck flatpak) before launching

The server reads the shortcut's Exec= line and extracts the Steam app ID from steam://rungameid/{id}.

Manual run (without systemd)

~/.local/bin/retrodeck-steamapprunner

Or from the repo during development:

PORT=8765 python3 server.py