---
date-created: 2026-10-21 08:47
date-modified: 2026-10-21 09:26
---
# RetroArch on Zeus design tree

## Facts

- Zeus is an `x86_64-linux` desktop with AMD graphics, 32-bit graphics support, Bluetooth, Hyprland, and Home Manager.
- Nixpkgs provides `pkgs.retroarch.withCores` for an explicit set of Libretro cores.
- Nixpkgs provides `pkgs.retroarch-free` and `pkgs.retroarch-full` for broad core sets.
- The packaged RetroArch version is 1.22.2 and includes Cloud Sync on Linux.
- Linux Cloud Sync uses a WebDAV endpoint.
- RomM requires RetroArch 1.22 or newer for this integration.
- RomM documents configuration synchronization as part of its Cloud Sync setup.
- Cloud Sync supports saves, configuration, thumbnails, and system files as separate categories.
- RomM matches a save or state to a ROM by its file name without the extension.
- Local ROM files must use the same names as their RomM library records.
- RomM 5.4 provides a WebDAV endpoint for RetroArch Cloud Sync.
- The endpoint is `https://games.alexion.dev/api/sync/retroarch/`.
- RomM stores its ROMs and BIOS files on Pikachu.

## Constraints

- Install RetroArch on Zeus.
- Start with PlayStation and Sega Saturn cores.
- Evaluate RetroArch Cloud Sync.
- Keep package selection declarative.
- Keep credentials out of the Nix store and version control.

## Decision tree

- D1 — Initial core selection [settled]
  - Use `beetle-psx-hw` for PlayStation.
  - Use `beetle-saturn` for Sega Saturn.
  - D4 — Core package viability [settled]
    - Both core packages support `x86_64-linux`.
    - Neither package is marked broken or unfree.
  - D5 — Package composition [settled]
    - Build a RetroArch wrapper with `beetle-psx-hw` and `beetle-saturn` only.
- D2 — Cloud Sync data scope [settled]
  - Sync saves, states, and configuration.
  - Do not sync thumbnails or system files.
  - D6 — Sync endpoint [settled]
    - Use RomM's RetroArch WebDAV endpoint.
  - D7 — Sync identity [settled]
    - Use the existing RomM account.
    - D15 — Credential injection [settled]
      - Store the RomM password in RetroArch's writable user configuration.
  - D8 — Synchronization mode [settled]
    - Synchronize automatically at startup and after play sessions.
    - D16 — Launch order [settled]
      - Do not add a game-launching frontend.
      - Start RetroArch before loading local ROM content.
  - D9 — Conflict and destructive-sync policy [settled]
    - Use non-destructive synchronization.
    - RetroArch backs up a local file when RomM reports its deletion.
- D3 — ROM and firmware access [settled]
  - Keep ROMs and BIOS files locally on Zeus.
  - D10 — Mount or replication method [settled]
    - Do not configure a remote mount or replication method.
  - D11 — RetroArch directory settings [settled]
    - Use `~/.local/share/retroarch/`.
    - Use `roms/`, `system/`, `saves/`, and `states/` subdirectories.
    - Keep saves and states outside the content directory.
    - Sort saves and states into per-core folders.
- D12 — User-configuration policy [settled]
  - Nix declares the package, cores, and directory defaults.
  - RetroArch manages and synchronizes its writable configuration.
- D13 — User-facing integration [settled]
  - Do not add a user-facing integration beyond RetroArch's desktop entry.
- D14 — Validation [settled]
  - Verify the NixOS evaluation and a manual Cloud Sync round trip.

## Frontier

No decisions remain open.

## Decision log

- D13: Do not add a user-facing integration beyond RetroArch's desktop entry.
- D16: Do not add a game-launching frontend. Start RetroArch before loading local ROM content.
- D14: Verify the NixOS evaluation and a manual Cloud Sync round trip.
- D12: Nix declares the package, cores, and directory defaults. RetroArch manages and synchronizes its writable configuration.
- D11: Use `~/.local/share/retroarch/` with `roms/`, `system/`, `saves/`, and `states/` subdirectories.
- D9: Use non-destructive synchronization.
- D8: Synchronize automatically at startup and after play sessions.
- D15: Store the RomM password in RetroArch's writable user configuration.
- D5: Build a RetroArch wrapper with `beetle-psx-hw` and `beetle-saturn` only.
- D3: Keep ROMs and BIOS files locally on Zeus.
- D10: Do not configure a remote mount or replication method.
- D7: Use the existing RomM account.
- D7 note: RomM accepts API client tokens as Bearer authentication. RetroArch Cloud Sync only supports WebDAV Basic authentication.
- D6: Use RomM's RetroArch WebDAV endpoint.
- D2: Sync saves, states, and configuration. Do not sync thumbnails or system files.
- D11: Keep saves and states outside the content directory. Sort them into per-core folders.
- D1: Use `beetle-psx-hw` for PlayStation and `beetle-saturn` for Sega Saturn.
- D4: Both selected core packages support Zeus and have no broken or unfree package status.