// OPENBOX DOCS

FAQ

Frequently asked questions about OpenBox, its data, and its limits.

Frequently asked questions

Does OpenBox include games or ROMs?

No. OpenBox does not distribute games, ROMs, BIOS files, firmware, or DRM circumvention tools. You supply the files; OpenBox catalogs, launches, and tracks them.

Does it require an online account?

No OpenBox account is required. Optional integrations may have their own accounts, credentials, API terms, and rate limits. RetroAchievements and EmuMovies use your existing accounts, and metadata syncing talks to the public LaunchBox Games Database with your consent.

What operating systems are supported?

OpenBox targets Linux, Windows x86_64 and ARM64 (x86_64 since 1.13.0; ARM64 since 2.0), and macOS 11 or newer on Apple Silicon and Intel (since 1.19.0).

  • Linux: desktops, laptops, Steam Deck systems, and handheld PCs on x86_64 and aarch64. Release artifacts are built for both architectures — pick the AppImage matching uname -m, and the built-in updater only offers the artifact matching the running architecture. Source builds need Rust 1.92+; packaged builds ship the Rust server with no Python runtime. Python 3.11+ is only for the fallback and .py plugins.
  • Windows: x86_64 and ARM64 (ARM64 since 2.0), installed from the signed portable package with install.ps1. Windows PowerShell 5.1 is enough; the installer needs neither curl nor OpenSSL.
  • macOS: the signed universal app bundle, installed with install-macos.sh into ~/Applications. The bundle ships the Rust openbox-server with no Python runtime and renders the UI in a WKWebView window. The installer needs python3 3.11 or newer on PATH to verify the release.

Linux stays the primary distro-integration target. See Installation, Windows, and macOS.

What are the requirements?

The runtime is dependency-free on every platform: standard library only (plus ctypes on Windows), no pip install, no requirements.txt, and no virtualenv.

PlatformInstallRequirements
LinuxAppImage, Flatpak, or sourceRust 1.92+ for source builds; no Python in packaged builds; WebKitGTK for the native window
WindowsSigned portable package via install.ps1Windows x86_64 or ARM64, Windows PowerShell 5.1; the WebView2 runtime for the native window (present on Windows 11 and most Windows 10 systems)
macOSSigned universal app bundle via install-macos.sh, or sourcemacOS 11 or newer on Apple Silicon or Intel; python3 3.11+ on PATH for the installer; WKWebView is built into macOS

Does OpenBox run on Windows?

Yes, since 1.13.0. Windows x86_64 and ARM64 install from the signed portable package using the published install.ps1, which verifies the release key, the archive checksum, and its Ed25519 signature before extracting to %LOCALAPPDATA%\OpenBox.

The launchers openbox.cmd and openbox.ps1 start the app; --web forces the browser app window. The native window is WebView2: the portable install ships native_host.exe compiled, and a source checkout either drops in the released OpenBox-x86_64-windows-native-host.exe as native_host.exe or builds it with powershell -File scripts/build_native_host_windows.ps1 (MSVC toolchain with the C++ workload). Until that binary exists, the launchers open the same UI in a browser app window, so Windows works out of the box either way. Python is found as python.exe / py.exe on PATH or via OPENBOX_PYTHON.

Windows gains the same adapters and launch tooling as Linux, because every bundled emulator definition carries its Windows executable name. macOS works the same way for the 37 definitions that name a macOS build (native_exe_macos). These stay Linux-only: gamescope and Steam Game Mode, AppImage and Flatpak packaging, XDG desktop entries, sudo make install, Steam Deck / handheld tuning, and Flathub-aware emulator management. See Windows and macOS.

Does OpenBox run on macOS?

Yes, since 1.19.0. Install the signed universal app bundle with the published install-macos.sh, which verifies the release key, the checksum, and the signature before it installs OpenBox.app into ~/Applications. The bundle is not notarized, so the first launch asks you to allow it in System Settings > Privacy & Security > Open Anyway. Library data lives in ~/Library/Application Support/openbox-game-launcher. Seven bundled emulator definitions have no verified macOS build and are reported as not installed. See macOS.

Is my data sent anywhere?

No. Nothing leaves your machine unless you explicitly trigger an integration: a metadata sync, a media download, a webhook delivery, statistics sync, or opt-in catalog sync to a folder you choose. There is no telemetry, no crash reporting, and no OpenBox account. The server binds to loopback only.

Can I run it alongside Steam, Heroic, and Lutris?

Yes. OpenBox reads their manifests and launches through them (steam -applaunch, heroic://, lutris:rungameid), so Steam Input, overlays, and client features keep working. It does not replace them. On Windows the same applies to the storefront clients you already run there; the manifest-import adapters are unchanged.

Where does my library live?

The default data directory is ~/.local/share/openbox-game-launcher on Linux, %LOCALAPPDATA%\openbox-game-launcher on Windows, and ~/Library/Application Support/openbox-game-launcher on macOS. The layout is the same on every platform: library.json with a last-known-good .bak beside it, written atomically with owner-only permissions, plus server.token, server.port, media, backups, themes, and logs.

Set OPENBOX_DATA_DIR before starting OpenBox to relocate it. A library directory moves between platforms unchanged: copy the folder and point OPENBOX_DATA_DIR at it, since the files are the same on every system. See Interfaces and data.

How do I get my saves backed up?

Use the Save management panel in a game's detail pane: scan for save locations, then back up. Versioned archives are stored under the game's folder in the data directory, with retention limits. Each archived file records its size, mode, modification time, and SHA-256; the restore dialog lists the archive contents, supports a dry run, and restores only the files you check after taking a safety backup. See Save discovery and restore.

How do I add an emulator?

Open Tools > Emulators & controllers, pick one from the catalog, and choose Install. On Linux, OpenBox adds the Flathub remote if missing and writes the platform profiles when the install finishes. On Windows and macOS, install the emulator yourself; OpenBox detects the executable and writes the platform profiles from the definition's native_exe_windows or native_exe_macos value. Native binaries on PATH are detected automatically on every platform. See Emulators and launching.

Do I need a LaunchBox subscription?

No. OpenBox is free and open source (AGPL-3.0). The workflows that LaunchBox gates behind Premium, like custom fields, ESRB filters, list view, media packs, and mounted-folder statistics sync, ship free here. The capability matrix lives in Parity.

Can I use a gamepad?

Yes. Since 1.8.0 the library grid and list support full keyboard and gamepad navigation (arrows/Home/End/Page, f favorite, Escape clear) with a configurable controller map, and Big Box is controller-native. See Library navigation and Big Box and handhelds.

Does it work on the Steam Deck?

Yes. The AppImage works on SteamOS and Bazzite, and --game-mode runs OpenBox as a guest inside Steam's gamescope session so Steam Input, the Quick Access Menu, and MangoHud stay with Steam. Steam Deck and handheld tuning are Linux-only: Windows and macOS have no gamescope, Game Mode, or handheld power/display tuning equivalent. See Steam Game Mode.

How do I update OpenBox?

The AppImage updates in place through the built-in updater, which verifies the release key, checksum, and signature and only offers the artifact matching the running architecture. Windows and macOS update by re-running the new release's installer.

Windows updates re-run the new release's install.ps1; it verifies the archive and keeps the previous tree at <InstallDir>\share\openbox.previous.

macOS updates use the same verification. They replace the app bundle after OpenBox exits, keep OpenBox.app.previous for rollback, and are refused while a game is running.

Do I need Wine or Proton?

OpenBox does not require Wine or Proton on any platform. On Windows, games run natively. On Linux, Windows-only titles run through the compatibility layer you already use, such as Steam Play or a Lutris Wine profile, and OpenBox launches them through that client. The Wine and Proton manager is Linux-only. OpenBox itself stays standard-library-only and bundles no compatibility layer of its own.

Can I script or automate it?

Yes. A token-authenticated REST API covers library, launch, saves, backups, themes, plugins, and automation. Python plugins hook six base points: library, before_launch, after_session, command, library_source, and events; since 1.18.0 they can also declare storefront, metadata, media, stats, emulator-settings, and discovery capabilities, which receive scoped read-only services. Webhooks deliver HMAC-signed events. See REST API, Plugins, and Webhooks.

OpenBox is an independent open-source project. It is not affiliated with LaunchBox, Unbroken Software, LLC, or the Openbox window manager. Those names appear only to describe compatibility and comparison boundaries. See Legal and trademarks.

What's new in 1.11 through 2.0?

1.19 (Platform parity): one capability contract decides every platform-specific control. 3.0: library format 7, /api/v2 as the public contract, the portable library, backup format 2, plugin API v2, and the Windows ARM64 lane — see the changelog.

1.11 (Every Second Counts): Quick Resume, Moments, clips/reels, Time Machine, Backlog Radio, Arcade Room/Museum kiosk, Household, Steam Bridge, ES-DE migration, SteamGridDB artwork, and local launcher trophies — see API 1.11 additions. 1.12 (Living Library): smart collections, per-game Story timelines, per-game launch_env/launch_confirm, opt-in weekly backups, SQLite self-enable at 5,000 games, palette recents, and the Living Library overview on the home page — see API 1.12 additions. 1.13 (Windows support): Windows x86_64 with the signed portable install.ps1, a WebView2 native window shipped compiled in the portable install, the same updater verification on Windows, and Windows executable names in every bundled emulator definition — see Windows and the release notes. Linux fixes in 1.13: process liveness no longer uses os.kill(pid, 0), stored references use POSIX separators on Windows, and the metadata database closes cached SQLite handles before replacing the file.

1.13.1 (Fixes): the sweep that made the Windows release usable — utility dialogs that opened invisibly, nested dialogs that all closed at once, a setup wizard that re-opened on every refresh, a session token that was dropped on reload, hidden tabs that could overwrite newer state, and "Reveal in Explorer" that never opened anything. 1.14 (Library intelligence): the 0–100 library health score, the Artwork Doctor, missing-file repair, duplicate merge, offline Game DNA search, Plugins 2.0, backlog management with your own star ratings, manual playtime, and dated notes, effortless metadata after import, ScreenScraper ROM-hash confidence, the thumbnail chooser, the Big Box boot option and on-screen keyboard, and Steam Bridge artwork. 1.15 (Finish the surface): motion that respects reduced motion, a readable light theme and the sixth stock theme High Contrast, signed emulator-definition updates, Time Machine Compare, Settings → About, the Windows uninstaller, broader screen-reader and touch-target support, and Story PNG export — see the release notes.

1.16 (Make it true): Check every game runs the Launch Doctor across your whole library and groups the results by cause, so 412 games blocked by one missing emulator read as a single line with one Install button; Preview changes shows what restoring a backup would remove, bring back, and overwrite before it happens; a game that fails to start now says so instead of reporting success; games the import wizard is unsure about wait for your decision rather than being imported on a guess; your own .m3u playlists are never overwritten; and the release closes five security defects that are not backported — if you are on 1.15.x or older, upgrading is the fix.

1.16.1 (Launch readiness everywhere): games that will not launch are badged on the grid, a group sharing one fix gets one button, a Flatpak emulator gets a read-only folder grant instead of a reinstall prompt, each game can choose its RetroArch core, and launch definitions cover 18 more systems. 1.17 (More of your library, and what it cost): installed GOG Galaxy, EA app, and Ubisoft Connect games import natively on Windows; Game Night decks save players, minutes, and a filter under a name and return a reproducible seed; games record a price paid and currency, and Play Insights shows cost per hour without converting currencies; server notices are translated into the five locales; and ScreenScraper lookups work again with the required developer credentials. See API 1.17 additions and the changelog.

1.18 (A clearer, deeper library): one Add games menu, a six-step Setup Center with the longer steps behind an advanced toggle, Help & shortcuts (F1 or ?), a single illustrated empty-library card, a dismissible onboarding checklist, a Jump back in card, and a theme swatch gallery; platform rename and delete in one place, a media queue that survives a restart with EmuMovies and provider ordering, save manifests with selective restore, plugin capabilities and repair, emulator and controller management, Big Box input/video/reader controls, storefront scan progress, and achievements, high scores, and netplay. See the changelog and API 1.18 additions.

Where do I report a bug or request a feature?

Use the GitHub issue templates: report a bug or request a feature. Include the diagnostic log from Settings > Advanced > Copy diagnostic log; it redacts tokens and passwords but can include game names and file paths.