dev/docs/00 INBOX/ai/retroarch-zeus-design-tree.md

date-created, date-modified

date-created	date-modified
2026-10-21 08:47	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.