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). Treat token-bearing URLs as secrets; prefer theX-OpenBox-Tokenheader for scripts and never paste or share the URL. - 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 vendor cloud lock-in, and no telemetry; optional mounted-folder sync stays under your control.
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.
Saved Backlog Radio searches pin as named smart collections that
re-evaluate live — the shelf stores the question, not the answer. Every game
gains a Story tab narrating its journey: added, first played, longest
session, milestones, progress, and captured Moments. The launch sheet gains
per-game KEY=value environment overrides and an optional confirm-before-
launch step, and an opt-in weekly automatic backup keeps a bounded archive
history with a last-run line in Settings. The SQLite read model self-enables
at 5,000+ games (env opt-out honored), and the command palette ranks recently
used games and actions first.
Quick Resume and Moments keep save-state-aware progress, captures, and session recaps close to the game you were playing. Record That adds replay-buffer clips and deterministic highlight reels. The Time Machine provides journal-backed history and safe as-of inspection, while Backlog Radio, the explainable natural query bar, and the command palette make a large backlog easier to navigate.
The Arcade Room and Museum mode turn the library into a controller-friendly
showcase, with an optional local kiosk PIN convenience boundary. Household
records provide opt-in, server-free challenges and leaderboards. Steam Bridge
can preview and manage non-Steam shortcuts, and ES-DE gamelist.xml imports are
reviewable before they change the library.
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, "What should I play?" smart picker (time, mood, familiarity, players) plus Surprise Me random selection, and a pan/zoomable Library Constellation relationship graph. Keyboard and gamepad navigation across the grid and list (arrows/Home/End/Page, f favorite, Escape clear, configurable controller map), hash routing so refresh and shared links restore platform/playlist/preset/query/selection/sort, sortable list-view columns with persisted direction, screenshot lightbox with prev/next/zoom, cover skeleton loading, and Mood Match adaptive cover theming that tints accents from the selected game.
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, ScreenScraper per-ROM-hash scraping (credentials in ~/.env, 1 req/s throttle, 30-day cache), optional SteamGridDB artwork search/apply and bulk matching for covers, backgrounds, clear logos, icons, and banners (credentials in ~/.env, local cache), 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, BIOS SHA1 drift detection in Launch Doctor. 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). OpenBox launcher trophies are a separate local, deterministic trophy case evaluated from library and history.
Local-first playtime analytics with a 366-day activity heatmap (levels 0–4), current and longest play streaks, 30-day play momentum, and top platforms/genres. OpenBox Wrapped prints your year in games (playtime, streaks, progress, busiest month), the History Timeline tab groups sessions by day, and the Mastery Map dashboard breaks the library into per-platform and per-decade progress bars with RetroAchievements columns. The launcher trophy case evaluates deterministic OpenBox milestones from local library/history data; these awards are separate from RetroAchievements. Computed entirely locally with zero telemetry.
Fullscreen Stage/Hybrid/CoverFlow layouts, gamepad navigation, screensaver/attract mode, optional startup video, library BGM, video snaps (looping gameplay videos in Stage mode with debounce and BGM ducking), Game Night party mode (couch-multiplayer queue, spinning wheel, up-next strip, persistent rounds), Steam Game Mode guest (--game-mode), gamescope presets (Steam Deck, Steam Deck HD, 1080p, 1440p, 4K, integer scale, stretch, borderless) plus custom user-defined presets with per-game override, MangoHud performance overlay toggle, controller bench with live gamepad SVG visualization, localization (English, Spanish, German, French, Portuguese).
Optional SQLite read model (OPENBOX_ENABLE_SQLITE_READ=1) with canonical name-substring search and JSON-equivalent facets for large libraries, wired into /api/v2/library/search. Backup diff API (GET /api/v2/backup/diff) to compare current library against archives. Visual chip builder for smart collection filter presets. Library export to JSON or CSV with platform/playlist scopes, shareable-by-construction field projection, and automatic newest-10 rotation. Statistics sync remains available through the mounted-folder workflow; the opt-in causal transport provides validated full-library sync with conflict review and tombstones, while legacy routes fail closed before mutation. LaunchBox XML migration import (POST /api/v2/import/launchbox/preview and /apply). Manual/shelf entries for games without local files.
For the review-first workflows, use the UI rather than copying paths or records by hand:
- LaunchBox XML: open the LaunchBox migration panel, choose one bounded XML export, review the parsed entries, path mappings, exclusions, and emulator mappings, then apply the preview. A changed file or library invalidates the preview and requires a new review; XML never supplies executable commands.
- Catalog sync: configure a mounted folder in Settings, enable library catalog sync, preview incoming changes, choose alternatives for conflicts, apply the reviewed plan, and publish local changes explicitly. Paths, launch commands, credentials, media, and play statistics remain local; the apply step creates a recovery backup first.
- Shelf entries: use Add shelf entry for a title without a local file. Shelf records can be edited, filtered, and exported, then converted to a playable entry only after selecting an existing absolute file.
The SQLite read model is opt-in and keeps JSON as the source of truth. The release gate covers 10,000 and 20,000-game libraries; behavior and performance beyond 20,000 games are exploratory.
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
Constellation: library relationship graph with series, developer, and genre edges
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 | Architecture-matched signed installer and 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 detects uname -m (override with OPENBOX_ARCH=x86_64 or OPENBOX_ARCH=aarch64), selects the matching AppImage, and verifies the release public-key pin, SHA-256 checksum, and Ed25519 signature before installing to ~/.local/bin:
VERSION=1.12.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. Release artifacts are built for both x86_64 and aarch64; pick the one matching your CPU (uname -m).
chmod +x OpenBox-$(uname -m).AppImage
./OpenBox-$(uname -m).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)
├── webapp_state.py SSE/event bus facade over the canonical state owner
├── routes.py GET/POST route tables (frozen v1 surface + additive v2 routes)
├── routes/ Route registry package (@route decorator, handler loading)
├── contracts.py Frozen v1 API contract + legacy aliases (v1_contracts.json)
├── openbox.py Shared core helpers (data paths, launch, profiles)
├── static/ Frontend JavaScript modules, search worker, and app.css
├── 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 adapter
├── importers.py Steam, Heroic, Lutris, ROM imports
├── automation.py HMAC-signed webhook delivery + event allowlists
├── backend_io.py Bounded network and filesystem helpers
├── cloud_sync.py Mounted-folder statistics sync
├── crash_report.py Redacted diagnostic report generator
├── notifications.py Persistent notification feed helpers
├── openbox_logging.py Diagnostic logging with secret redaction
├── play_queue.py Persistent play queue helpers
├── archives.py Safe, cached archive extraction
├── arcade.py MAME and FinalBurn full-set import
├── pkg/state/ Modularized state, caches, launch, and operations
├── pkg/parity/ Parity modules (flat `import parity_*` via MetaPathFinder bridge)
├── 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_runner.py Sandboxed plugin subprocess runner
├── 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 Standalone test files run by ./run_all_tests.sh
./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.