Skip to content
BranchesTags

Repository files navigation

eisoDOS

A lightning fast game launcher for eXoDOS, eXoWin3x, and eXoWin9x collections mounted locally. Runs on Linux, macOS, and Windows. Browse, search, and launch 7,600+ DOS games, 1,140+ Windows 3.x games, and 635+ Windows 9x games with DOSBox and 86Box integration within a couple of seconds. Sub-second filtering/searching, local game caching with on-the-fly ZIP extraction, and automatic config adaptation for cached game copies.

Features

  • CLI interface with 7 subcommands: list, run, info, cache, config, scan, resolve
  • TUI interface (default) with fuzzy search, sortable/scrollable game list, game details panel, an in-app settings screen, and a per-game config override editor
  • DOSBox and 86Box auto-detection across native installs, Flatpak, and Snap (Linux), Homebrew/.app (macOS), or Program Files/PATH (Windows)
  • Multi-collection support for eXoDOS (DOS), eXoWin3x (Windows 3.x), and eXoWin9x (Windows 9x) with per-platform filtering
  • Auto-extraction of XML catalog, game metadata, and game data from eXoDOS/eXoWin3x/eXoWin9x zips
  • Binary index caching for fast startup with large catalogs (bincode serialization)
  • Game file caching with zip extraction and recursive copy support
  • Win3.1 base sharing via hardlinks — a shared Windows 3.1 base is extracted once and hardlinked into each Win3x game cache, saving significant disk space
  • Win9x VHD parent sharing — shared 86Box/DOSBox-X parent virtual disks (~2 GB) are extracted once and hardlinked (or copy-on-write reflinked, on filesystems that support it) into a small per-game child VHD at launch
  • Config adaptation rewrites relative paths in DOSBox conf and 86Box cfg files for cached game copies, confined to the cache directory

Prerequisites

  • A DOSBox variant: DOSBox-X (recommended), DOSBox Staging, or classic DOSBox
  • An eXoDOS v6 collection (mounted locally or, if you prefer, extracted)
  • Optionally, an eXoWin3x collection for Windows 3.x games
  • Optionally, an eXoWin9x collection for Windows 9x games — needs 86Box (preferred) or DOSBox-X (fallback for some titles)

Quick Start

  1. Install a DOSBox variant (DOSBox-X recommended), and 86Box if you have an eXoWin9x collection
  2. Mount (preferred) or extract (why?!) your eXoDOS v6 collection
  3. Install eisoDOS: make install (Linux/macOS) or cargo install --path crates/eisodos (all platforms)
  4. Configure: set source_path in your config file to your eXoDOS directory (and optionally win3x_source_path for eXoWin3x, win9x_source_path for eXoWin9x)
    • Linux/macOS: ~/.config/eisodos/config.toml
    • Windows: %APPDATA%\eisodos\config.toml
  5. Run: eisodos

Setup

1. Configure eisodos

# Show config file location and current settings
eisodos config show

# Edit the config file
# Set source_path to your eXoDOS root directory
$EDITOR ~/.config/eisodos/config.toml        # Linux/macOS
notepad %APPDATA%\eisodos\config.toml        # Windows

Example config.toml:

# Linux/macOS
source_path = "/mnt/exodos"
win3x_source_path = "/mnt/exowin3x"   # optional
win9x_source_path = "/mnt/exowin9x"   # optional

# Windows (mapped network drive or local path)
source_path = "Z:\\eXoDOS"
win3x_source_path = "Z:\\eXoWin3x"    # optional
win9x_source_path = "Z:\\eXoWin9x"    # optional

eisodos will automatically:

  • Extract the XML catalog from Content/XODOSMetadata.zip (Content/XOWin3xMetadata.zip for Win3x, Content/XOWin9xMetadata.zip for Win9x)
  • Extract game metadata from Content/!DOSmetadata.zip (Content/!Win3Xmetadata.zip, Content/!Win9Xmetadata.zip) on demand
  • Extract game data from eXo/eXoDOS/*.zip (eXo/eXoWin3x/*.zip, eXo/eXoWin9x/<year>/*.zip) when launching games
  • For Win3x games, create a shared Windows 3.1 base and hardlink common files to save disk space
  • For Win9x games, extract shared 86Box/DOSBox-X parent VHDs once and hardlink (or CoW-reflink) them into each game's cache

Other optional settings — editable in the TUI settings screen (F2) or directly in the TOML:

Field Purpose
preferred_dosbox Force a specific DOSBox variant instead of auto-priority (dosbox-x > staging > classic)
dosbox_path Explicit path to a DOSBox executable; skips auto-detection
eighty_six_box_path Explicit path to an 86Box executable; preferred for Win9x games
mt32_rom_dir Directory with MT-32 ROM/SoundCanvas files, rewritten into DOSBox conf for MT-32 sound

2. Mount your eXoDOS collection

If your eXoDOS collection lives on a NAS or network share, mount it first.

Linux (SMB)

sudo mount -t cifs //nas/exodos /mnt/exodos -o username=USER,uid=$(id -u),gid=$(id -g)

To mount at boot, add to /etc/fstab:

//nas/exodos /mnt/exodos cifs username=USER,password=PASS,uid=1000,gid=1000 0 0

Linux (NFS)

sudo mount -t nfs nas:/volume1/exodos /mnt/exodos

To mount at boot, add to /etc/fstab:

nas:/volume1/exodos /mnt/exodos nfs defaults 0 0

macOS

Open Finder, press Cmd+K, and enter smb://nas/exodos or nfs://nas:/volume1/exodos. The share appears under /Volumes/exodos.

Or via terminal:

# SMB
mount_smbfs //USER@nas/exodos /Volumes/exodos

# NFS
sudo mount -t nfs nas:/volume1/exodos /Volumes/exodos

Windows

Map a network drive in File Explorer (right-click "This PC" > "Map network drive") to \\nas\exodos, or via command line:

net use Z: \\nas\exodos /persistent:yes

Then set source_path in your config to the mount point (/mnt/exodos, /Volumes/exodos, or Z:\eXoDOS).

3. Build the index

eisodos scan

This parses the LaunchBox XML and creates a binary index for fast lookups.

4. Verify emulator detection

eisodos resolve

Shows all detected DOSBox and 86Box installations and which one is selected.

Usage

TUI mode (default)

eisodos

Opens a terminal UI with:

  • Search: Type to fuzzy-search game titles (always active)
  • Navigate: Up/Down arrow keys, PageUp/PageDown (jump 20), Home/End
  • Launch: Enter to run selected game
  • Sort: Tab to cycle sort order
  • Platform filter: Ctrl+P to cycle All → DOS → Win3x → Win9x → All
  • Cached-only filter: Ctrl+F to show only cached games
  • Delete cache: Delete key or Ctrl+D to remove cached game files
  • Settings: F2 to edit source paths, preferred DOSBox, MT-32 dir, and other config in-app
  • Per-game config editor: F3 to override a game's DOSBox conf/86Box cfg fields (F4 opens it in your external $EDITOR)
  • Clear search: Esc
  • Quit: Ctrl+Q or Ctrl+C

CLI commands

eisodos list                    # List all games (DOS + Win3x + Win9x)
eisodos list "doom"             # Fuzzy search for games
eisodos list --platform dos     # List DOS games only
eisodos list --platform win3x   # List Win3x games only
eisodos list --platform win9x   # List Win9x games only
eisodos info "DOOM"             # Show game details
eisodos run "DOOM"              # Launch a game
eisodos run "Minesweeper" --platform win3x  # Launch a Win3x game
eisodos scan                    # Rebuild the game index
eisodos resolve                 # Show DOSBox/86Box installations
eisodos config show             # Show configuration
eisodos config path             # Print config file path
eisodos cache list              # List cached games
eisodos cache remove <game-id>  # Remove a game from cache
eisodos cache clear             # Clear entire cache
eisodos cache update            # Re-adapt DOSBox/86Box configs for all cached games
eisodos cache clear-bases       # Remove shared Win3.1/Win9x base files (VHD parents)

Collection Directory Structures

eXoDOS

<exodos_root>/
  xml/all/MS-DOS.xml              <- Game catalog (auto-extracted from XODOSMetadata.zip)
  eXo/eXoDOS/
    !dos/<game_folder>/           <- Game metadata (auto-extracted on demand)
      dosbox.conf
      *.bat
    <game>.zip                    <- Game data (auto-extracted on launch)
  Content/
    XODOSMetadata.zip             <- Source for catalog XML
    !DOSmetadata.zip              <- Source for game metadata

eXoWin3x

<exowin3x_root>/
  xml/Windows 3x.xml             <- Game catalog (auto-extracted from XOWin3xMetadata.zip)
  eXo/eXoWin3x/
    !win3x/<game_folder>/        <- Game metadata (auto-extracted on demand)
      dosbox.conf
      *.bat
    <game>.zip                   <- Game data (each contains a full Windows 3.1 install)
  Content/
    XOWin3xMetadata.zip          <- Source for catalog XML
    !Win3Xmetadata.zip           <- Source for game metadata

Win3x games run Windows 3.1 inside DOSBox. Each game zip includes a full Windows 3.1 installation (~243 files), but eisodos optimizes this by extracting a shared base once and hardlinking common files into each game's cache directory.

eXoWin9x

<exowin9x_root>/
  xml/all/1994-1996.9x            <- Game catalog (auto-extracted from XOWin9xMetadata.zip)
  eXo/eXoWin9x/
    !win9x/<year>/<game_folder>/  <- Game metadata (auto-extracted on demand)
      Play.cfg (86Box) or Play.conf (DOSBox-X)
      *.bat
    <year>/<game>.zip              <- Game data: VHD + media (auto-extracted on launch)
  eXo/util/
    utilWin9x.zip                  <- Shared 86Box/DOSBox-X parent VHDs (nested zip)
  Content/
    XOWin9xMetadata.zip            <- Source for catalog XML
    !Win9Xmetadata.zip             <- Source for game metadata

Win9x games run inside 86Box (preferred) or DOSBox-X (fallback) using a VHD parent/child differencing setup: shared parent VHDs (~2 GB total, each a full Windows 9x install) are extracted once and hardlinked — or copy-on-write reflinked, on filesystems that support it — into a small per-game child VHD at launch.

Building and Installation

Building from source

cargo build --release

The binary is at target/release/eisodos.

Installation

# Linux/macOS
make install                          # Installs to ~/.local/bin/eisodos
sudo make install PREFIX=/usr/local   # System-wide install

# All platforms (via cargo)
cargo install --path crates/eisodos

Releasing

scripts/release.sh 0.3.0    # accepts v0.3.0 too

This bumps the version in both Cargo.toml files, commits, creates an annotated git tag, and pushes everything. The binary's --version output is derived from the git tag at build time via build.rs, so it always stays in sync.

Architecture

Two-crate workspace:

  • eisodos-core - Library with game catalog parsing (eXoDOS + eXoWin3x + eXoWin9x), DOSBox/86Box resolver, game runner, cache management, and configuration
  • eisodos - Binary with CLI (clap) and TUI (ratatui/crossterm), supporting per-platform filtering, an in-app settings screen, and per-game config overrides

Known Limitations

  • The TUI holds the full merged game list (DOS + Win3x + Win9x) in memory for the session. Acceptable at the current catalog size (~9,000 games) but not index-backed.
  • MT-32/SoundFont paths (.\mt32) in some DOSBox configs may not resolve if the shared MT-32 files are not in the game cache.
  • Win9x launches copy (or CoW-reflink, on filesystems that support it) a shared parent VHD into a per-game child VHD every launch. On non-CoW filesystems (e.g. ext4) this is a ~350-450 MB copy per launch, adding a few seconds of I/O.

License

MIT License. See LICENSE for details.

About

Fast terminal launcher for eXoDOS, eXoWin3x, and eXoWin9x — browse and launch "over 9000" DOS and Windows 3.x/9x games with fuzzy search, auto DOSBox/86Box detection, and smart game caching. Linux, macOS, Windows.

Topics

86oxclidos-gamesdosboxdosbox-xemulationexodosgame-launcherlaunchboxretro-gamingretrocomputingtuiwindows-9x

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages