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.
openboxopens a native WebKitGTK window by default, and falls back to a chrome-less app window (then your default browser) when WebKitGTK is missing.openbox --webskips the native window and opens the loopback web UI in a browser; from source,python3 web_app.pyalso opens the browser automatically with the token in the URL. To open the UI manually, append the token from the data directory, e.g. openhttp://127.0.0.1:PORT/?token=$(cat ~/.local/share/openbox-game-launcher/server.token). - 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 for Linux. It puts Steam, Heroic (Epic/GOG/Amazon), Lutris, Faugus, Gameyfin, ROM folders, ScummVM, RPCS3, Vita3K, and Eden Switch collections, and local executables in one searchable catalog with advanced search, ordered playlists, artwork galleries, session tracking, save and library backups, launch profiles, and controller-ready Big Box mode. No account, no cloud, no telemetry.
OpenBox Game Launcher is unrelated to Openbox, the open-source Linux window manager. The projects have different maintainers, codebases, and purposes.
OpenBox provides one UI over two hosts:
| Host | Entry point | Best for |
|---|---|---|
| Native window | openbox or openbox-native |
Default desktop use; one WebKitGTK window renders the full UI |
| Web UI | openbox --web or python3 web_app.py |
Development and debugging; full feature set, REST API, Big Box mode |
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 in the 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 (requires Node.js 22.12+; run cd scripts && npm ci first for Puppeteer).
| Method | Best for | Notes |
|---|---|---|
| AppImage (installer) | Desktop, Steam Deck, handhelds, immutable systems | Built-in verified updater, installs to ~/.local/bin |
| AppImage (manual) | Offline or custom path | chmod +x and run, no install step |
| Flatpak | Sandboxed installs | flatpak-builder from manifest |
| Source | Development, patching | git clone and python3 web_app.py |
| System | Install to /usr/local |
sudo make install |
Download the installer from a specific signed release, inspect it, then run it. The installer verifies the release public-key pin, SHA-256 checksum, and Ed25519 signature before installing to ~/.local/bin:
VERSION=1.5.1
curl --proto '=https' --tlsv1.2 --fail --location \
--output install.sh \
"https://github.com/vindeckyy/OpenBoxGL/releases/download/v${VERSION}/install.sh"
less install.sh
OPENBOX_RELEASE_TAG="v${VERSION}" bash install.shTo launch OpenBox right after installing, pass --run after the tag-pinned invocation:
OPENBOX_RELEASE_TAG="v${VERSION}" bash install.sh --runOmit OPENBOX_RELEASE_TAG only when you intentionally want the latest stable release. Install to a different directory with OPENBOX_INSTALL_DIR (for example, OPENBOX_INSTALL_DIR="$HOME/Applications").
Download the latest release from GitHub Releases.
chmod +x OpenBox-x86_64.AppImage
./OpenBox-x86_64.AppImageThe AppImage opens the native window by default. To use the loopback web UI instead, pass --web:
./OpenBox-x86_64.AppImage --webDesktop 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 # Native window (default)
openbox --web # Web UI (development)flatpak-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. The native window additionally needs WebKitGTK 4.1 (make native-host builds native_host); python3 web_app.py runs without it.
Optional local configuration can be loaded from an explicit OPENBOX_ENV_FILE, the data directory (or its parent), ~/.env, or ~/.config/openbox-game-launcher/.env. 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, Faugus, ROM folders, arcade, Gameyfin |
| Proton & Wine | Windows game runners, Wine prefixes, and Proton runtime environments |
| 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 |
| docs/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/
├── native_host.c Native WebKitGTK host (spawns web_app.py)
├── handlers/ Route handler mixins (library, media, imports, settings, ...)
├── web_app.py Loopback server + REST API (shared core)
├── routes.py GET/POST route tables (110 GET + 139 POST entries; v1_contracts.json freezes 60 paths)
├── contracts.py Frozen v1 API contract + legacy aliases
├── openbox.py Shared core helpers (data paths, launch, profiles)
├── state_store.py Schema-versioned state, atomic writes, snapshots
├── settings_schema.py Settings key whitelist
├── api_errors.py Structured API error codes
├── job_manager.py Background job lifecycle
├── importers.py Steam, Heroic, Lutris, ROM imports
├── pkg/parity/parity_*.py Parity modules (shim at root for compat)
├── 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
├── tests/test_*.py Test suite (62 files)
./run_all_tests.shBuild the native window host and the AppImage:
make native-host # WebKitGTK window host (needs libwebkit2gtk-4.1)
./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.