Local-first game library and launcher for Linux
Quick Start | Overview | Why OpenBox on Linux | Features | Screenshots | Installation | Documentation | REST API | FAQ | Development | Legal
One library for Steam, ROMs, and emulators. Click for more screenshots.
- Install. Grab the latest AppImage, or run from source with
python3 web_app.py(Python 3.10+). - Open the UI. It opens in a chrome-less app window by default and falls back to your default browser when no compatible browser can open one. The Settings panel controls this, and
--app-window/--no-app-windowoverride it at launch. From source you can also open the printed URL directly. - Import games. Click Import Folder and point at a directory of
.shfiles, or Import Steam to scan your installed games. - Press PLAY. Sessions, play time, and history are tracked automatically.
For ROMs, emulators, Big Box, RetroAchievements, and everything else — see Getting started and Installation.
OpenBox Game Launcher is an open-source game library manager and launcher built for Linux. It puts PC games, storefront libraries, ROM collections, arcade sets, and emulator workflows in one searchable catalog with advanced search, ordered playlists, artwork galleries, session tracking, save and library backups, and launch profiles.
OpenBox Game Launcher is unrelated to Openbox, the open-source Linux window manager. The projects have different maintainers, codebases, and purposes.
OpenBox provides two interfaces:
| Interface | Entry point | Best for |
|---|---|---|
| Web UI | python3 web_app.py or openbox |
Full feature set, REST API, Big Box mode |
| Native UI | python3 openbox.py or openbox-native |
Lightweight desktop use |
Library data is stored locally at ~/.local/share/openbox-game-launcher/library.json. Set the OPENBOX_DATA_DIR environment variable to use a different data directory.
Independence notice: OpenBox Game Launcher is an independent open-source project. It is not affiliated with LaunchBox, Unbroken Software, LLC, or the Openbox window manager project. LaunchBox and Big Box are trademarks of Unbroken Software, LLC. See DISCLAIMER.md.
LaunchBox has no native Linux build and charges Premium for workflows that OpenBox includes free. Key differences:
| Topic | OpenBox | LaunchBox on Linux |
|---|---|---|
| License | AGPL-3.0, full source | Proprietary, no Linux build |
| Cost | Free, no subscription | Premium paywall for advanced workflows |
| Data | Local JSON, no account | Cloud library (Premium) |
| Linux-native | Steam, Heroic, Lutris, RetroArch, ROMs, Arcade | Windows-first, Linux via compatibility layers |
| Automation | Local REST API with token auth | Limited external automation surface |
| Handheld / couch use | Big Box mode with controller navigation, AppImage portability, Steam Game Mode guest (--game-mode) |
Big Box exists, but Linux handheld workflows are secondary |
Consider OpenBox if you:
- Run Linux on a desktop, laptop, Steam Deck, or handheld PC
- Want one library for Steam, Heroic, Lutris, Gameyfin, ROMs, and standalone emulators
- Prefer local JSON library state over vendor cloud lock-in
- Need Flathub-aware emulator install/update flows
- Want RetroAchievements, save backups, session history, and Big Box in one app
The full capability matrix with acceptance checks lives in PARITY.md.
One catalog for Steam, Heroic, Lutris, Gameyfin, ROM folders, ScummVM, RPCS3, Vita3K, and local executables. Advanced search, collections, playlists, tags, bulk edits, custom fields, ESRB filtering, list view, and Surprise Me random selection.
LaunchBox Games Database sync (covers, backgrounds, screenshots, box backs, spines, 3D boxes, clear logos, fanart, banners, title screens, carts, discs, and advertisement flyers), IGDB search, Steam/GOG media, EmuMovies, Bezel Project, bundled media packs (platform logos, controller prompts, badges), duplicate cleanup, region priority, download limits.
Auto-detect emulators on $PATH, Flathub install/update, YAML definition packs, archive extraction (ZIP/7z/RAR), safe tokenized commands, per-game launch overrides. Example emulator profile:
SNES = retroarch -L /usr/lib/libretro/snes9x_libretro.so "{path}"
Tokens: {path}, {name}, {rom_name}, {app_id}, {heroic_app_id}, {lutris_id}.
Play time tracking, session history, save discovery (Steam Cloud, RetroArch, PCSX2, PPSSPP, RPCS3, Dolphin, Cemu), versioned backups with retention limits, Ludusavi/Hoard CLI hooks, RetroAchievements (hardcore, beaten, mastered, badge injection).
Fullscreen Stage/Hybrid/CoverFlow layouts, gamepad navigation, screensaver/attract mode, optional startup video, library BGM, Steam Game Mode guest (--game-mode), localization (English; more languages planned).
REST API with token auth, Python plugins (library, before_launch, after_session hooks), local CSS themes with live reload, HMAC-signed webhooks, mounted-folder statistics sync, openbox:// deep links.
Full feature list → Documentation
Library: grid and list views, platform filters, ordered playlists, status badges, and drag-and-drop import
Game detail: metadata, ratings, play history, hero art, and one-click launch
Big Box: fullscreen controller navigation with Stage layout
Screenshots use real LaunchBox metadata and cover art. Regenerate with python3 scripts/capture_readme_screenshots.py (see scripts/package.json).
Downloads the latest AppImage from GitHub Releases, verifies its SHA-256 checksum, and installs it to ~/.local/bin:
curl -fsSL https://raw.githubusercontent.com/vindeckyy/OpenBoxGL/master/scripts/install.sh | bashTo also launch OpenBox right after installing:
curl -fsSL https://raw.githubusercontent.com/vindeckyy/OpenBoxGL/master/scripts/install.sh | bash -s -- --runThe script resolves the latest release automatically, checks the AppImage against its published SHA-256 before installing, and adds a friendly openbox launcher. Install to a different directory with OPENBOX_INSTALL_DIR (e.g. OPENBOX_INSTALL_DIR="$HOME/Applications").
Download the latest release from GitHub Releases.
chmod +x OpenBox-x86_64.AppImage
./OpenBox-x86_64.AppImageTo launch the Tk interface from the AppImage, pass --native:
./OpenBox-x86_64.AppImage --nativeDesktop integrators such as Gear Lever work with the AppImage. If an older build opened then never showed a window after integration, install v0.6.0 or newer, remove the old menu entry, and re-add the AppImage.
sudo make install
openbox # Web UI
openbox-native # Native UIflatpak-builder --user --install --force-clean build-dir io.openbox.GameLauncher.yml
flatpak run io.openbox.GameLaunchergit clone https://github.com/vindeckyy/OpenBoxGL.git
cd OpenBoxGL
python3 web_app.pyRequirements: Python 3.10 or newer on a Linux system with standard desktop tooling.
Optional local configuration can be loaded from ~/.env or a project .env file. See .env.example. Never commit secrets.
The full user documentation is at openboxgl.github.io.
| Resource | What it covers |
|---|---|
| Getting started | First-run walkthrough with disposable folder |
| Installation | AppImage, Flatpak, source, troubleshooting |
| Library overview | Browse, search, filters, health audit |
| Importing | Steam, Heroic, Lutris, ROM folders, arcade, Gameyfin |
| Emulators and launching | Profiles, tokens, archives, dependency checks |
| Big Box and handhelds | Layouts, gamepad, gamescope, TDP profiles |
| Sessions, saves, and backups | History, save discovery, versioned backups |
| RetroAchievements | Matching, hardcore, badge injection |
| Plugins | Install, hooks, safe mode |
| REST API | Full endpoint documentation |
| PARITY.md | LaunchBox capability matrix |
| SUPPORT.md | Supported platforms, runtimes, and reporting guidance |
| docs/reliability.md | Edge case catalog and expected behavior |
| CHANGELOG.md | Release history |
| CONTRIBUTING.md | Development workflow and contribution guidelines |
| SECURITY.md | Security reporting process |
The Web UI exposes a local REST API for automation. Authenticate with X-OpenBox-Token:
# Find your token and port (only while the Web UI is running)
cat ~/.local/share/openbox-game-launcher/server.token
cat ~/.local/share/openbox-game-launcher/server.port
# List your library
TOKEN=$(cat ~/.local/share/openbox-game-launcher/server.token)
PORT=$(cat ~/.local/share/openbox-game-launcher/server.port)
curl -H "X-OpenBox-Token: $TOKEN" http://127.0.0.1:$PORT/api/library | jq '.games | length'
# Launch a game by stable ID
curl -X POST -H "X-OpenBox-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": "GAME_ID"}' \
http://127.0.0.1:$PORT/api/launchFull endpoint documentation: REST API.
No. OpenBox does not distribute games, ROMs, BIOS files, firmware, or DRM circumvention tools. You supply the files; OpenBox catalogs, launches, and tracks them.
No OpenBox account is required. Optional integrations (RetroAchievements, EmuMovies, IGDB) have their own accounts and credentials. The library is stored locally under your control.
OpenBox targets Linux (desktop, Steam Deck, handhelds). Windows-only features are documented as boundaries in PARITY.md. If you need Windows, LaunchBox remains a strong option.
OpenBox/
├── web_app.py Web UI server + REST API
├── openbox.py Native Tk UI
├── importers.py Steam, Heroic, Lutris, ROM imports
├── parity_*.py Parity modules (storefront, saves, media, discovery, integrations, etc.)
├── emulators.py Emulator profiles + Flathub management
├── metadata.py LaunchBox DB sync + media scraping
├── retroachievements.py RA matching + badge injection
├── saves.py Save discovery + backup engine
├── updates.py Verified GitHub updater
├── env_config.py .env loading + credential aliases
├── plugins.py Plugin lifecycle + hooks
├── plugin_catalog.py Bundled community catalog
├── catalog.py Search, filters, bulk edits
├── stock_themes.py Bundled CSS theme installer
├── themes/ Stock themes (5 CSS files)
├── emulator_defs/ YAML definition packs
├── scripts/ Build, test, screenshot capture
└── test_*.py Test suite
./run_all_tests.shBuild the AppImage:
./build_appimage.shPull requests should pass the full test suite. See CONTRIBUTING.md.
OpenBox Game Launcher is released under the GNU Affero General Public License v3.0.
Trademark references to LaunchBox, Steam, Heroic, Lutris, RetroArch, and other third-party products are used for compatibility description only. OpenBox does not distribute ROMs, BIOS files, firmware, or DRM circumvention tools.
For the full legal policy, see DISCLAIMER.md and TRADEMARKS.md.
OpenBox is free and open source (AGPL-3.0). If it saves you time, a coffee helps cover hosting and development:
Contributions are welcome. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening a pull request.