exogui

Important: This application requires eXo projects to be pre-patched with the Linux patch. For download and installation instructions, please visit the Retro-Exo Linux Guide and the Linux Patch Wiki.

The launcher for Retro eXo Projects.

🍎 macOS users: exogui binaries are not code signed and not notarized. macOS blocks downloaded builds ("exogui is damaged and can't be opened"), and on Apple Silicon the app won't launch until it is locally (ad-hoc) signed. After moving the app into place, run:

xattr -cr /Applications/exogui.app
codesign --force --deep --sign - /Applications/exogui.app
open /Applications/exogui.app

These one-time steps are unavoidable without a paid Apple Developer account. See Troubleshooting for details.

Links

• eXo Projects - Official eXo projects website
• Retro-Exo Linux Guide - Linux setup guide
• exogui discord - exogui-specific support

About

exogui is an Electron-based desktop application for browsing, managing, and launching games from the eXo projects. It is based on BlueMaxima's Flashpoint Launcher and reads LaunchBox-format XML configuration files.

Supported eXo Projects

Currently supported:

• eXoDOS
• eXoDREAMM
• eXoDemoscene

More eXo projects coming in the future!

Features

• Browse and search through the entire eXo game collections
• Launch DOS and Windows games with platform-specific configurations
• Manage playlists and favorites
• Cross-platform support (Windows, Linux, macOS)
• Integration with game metadata, screenshots, videos, and interactive 3D box viewer
• Online auto-updates with stable and beta channels (Linux AppImage)

macOS Builds

Two macOS builds are produced automatically by the CI workflow, each built natively for its architecture:

• Apple Silicon build (arm64) — for Apple Silicon Macs (M1 and later), built with the current Electron version
• Legacy build (Intel x64) — for Intel Macs, built with an older Electron version for maximum compatibility

⚠️ Security notice: The legacy (Intel) build uses an older version of Electron (v37). Older Electron versions may contain unpatched security vulnerabilities, so avoid using it to browse untrusted content.

If you encounter any issues with exogui, seek help on the exogui discord server. For general Retro eXo Projects support and Linux setup, visit the Retro eXo Projects Discord server.

Installation

Note: The Linux patch and macOS patch distributed by the Retro eXo Projects already include exogui — no manual installation is needed if you installed via the patch. This section is for manually updating exogui or setting it up without the patch.

exogui must be placed inside an exogui subfolder directly within the root of your eXo project. This is where it looks for game data by default (exodosPath: "../").

Directory layout

eXoDOS/               ← eXo project root (eXoDOS, eXoDREAMM, etc.)
├── exogui/           ← create this folder and place exogui here
│   └── <exogui files>
├── eXo/
├── Data/
└── ...

Examples by platform

Linux — AppImage

Download exogui.AppImage, place it in the exogui subfolder, and make it executable:

eXoDOS/
└── exogui/
    └── exogui.AppImage

chmod +x exogui.AppImage
./exogui.AppImage

Linux — tar.gz

Extract the archive into the exogui subfolder:

eXoDOS/
└── exogui/
    ├── exogui
    └── (other extracted files)

# Replace x64 with arm64 if you're on a 64-bit ARM machine
tar -xzf exogui.x64.tar.gz -C eXoDOS/exogui/
./eXoDOS/exogui/exogui

macOS — .app bundle

Extract the zip and move exogui.app into the exogui subfolder:

eXoDOS/
└── exogui/
    └── exogui.app

Double-click exogui.app to launch, or from Terminal:

open eXoDOS/exogui/exogui.app

Windows — zip

Extract the zip into the exogui subfolder:

eXoDOS\
└── exogui\
    ├── exogui.exe
    └── (other extracted files)

Run exogui.exe. The Windows NSIS installer (.exe setup file) handles this placement automatically.

Overriding the eXo project path

If you cannot follow the above layout, open exogui/config.json and set exodosPath to the absolute path of your eXo project root:

{
    "exodosPath": "/path/to/eXoDOS"
}

Development Setup

This project is currently intended for developers. To set up your development environment:

1. Clone the repository with submodules:

   git clone --recurse-submodules https://github.com/exogui/exogui launcher
   cd launcher

2. Install dependencies:

   npm install

3. Run in development mode (recommended approach):

   • Terminal 1: Start the watch process to rebuild on changes

     npm run watch

   • Terminal 2: Start the application

     npm run start

Alternatively, you can build once and run:

npm run build
npm run start

Package Scripts

Common Commands

• npm run build - Build the launcher (main, renderer, and static files to ./build/)
• npm run watch - Build and incrementally rebuild on source file changes
• npm run start - Run the latest build of the launcher
• npm test - Run Jest tests
• npm run lint - Run ESLint

Packaging

• npm run pack - Package the latest build (outputs to ./dist/)
• npm run release - Build and package in one step

Platform-Specific Packaging

• npm run pack:linux - Package for Linux (x64)
• npm run pack:linux-arm64 - Package for Linux (arm64)
• npm run pack:windows - Package for Windows (x64)
• npm run pack:mac-arm64 - Package for macOS (Apple Silicon)
• npm run pack:mac-x64 - Package for macOS (Intel)
• npm run pack:mac-universal - Package for macOS (universal arm64 + x64)
• npm run pack:all - Package for all platforms

Use release:* variants (e.g., npm run release:linux) to build and package in production mode.

Note: You can also set environment variables PACK_PLATFORM and PACK_ARCH to customize packaging.

Configuration Files

exogui uses several JSON configuration files to control its behavior:

• config.json - Application configuration (paths, ports, native platforms)
• preferences.json - User preferences (UI settings, theme, window size)
• mappings.json - File extension to application mappings (for opening manuals, videos, etc.)
• platform_options.json - Platform-specific options (file watching)

Documentation

• docs/architecture.md - Detailed architecture overview and socket communication
• docs/image-caching.md - How images are served and how grid thumbnails are generated and cached
• docs/online-updates.md - Online updates for Linux AppImage
• docs/troubleshooting.md - Troubleshooting guide for common issues