// OPENBOX DOCS
Installation
Install OpenBoxGL 3.0 on Linux with AppImage, Flatpak, or source, on Windows with the signed portable installer, or on macOS with the signed universal app bundle.
OpenBoxGL 3.0 runs on Linux, natively on Windows since 1.13.0, and natively on macOS since 1.19.0. Every packaged build ships the native Rust server openbox-server with no bundled Python runtime. On Linux the AppImage is the recommended path. On Windows the signed portable installer is the supported path; it is covered in full on the Windows page. On macOS the signed universal app bundle installs with install-macos.sh, and the macOS page covers it in full.
There is no OpenBox account, installer wizard, or license key. Downloading a release or cloning the repository is the entire installation.
Decide which package to use
| Package | Best for | Updates |
|---|---|---|
| AppImage | Desktop, Steam Deck, handhelds, immutable systems | Built-in verified updater |
| Flatpak | Sandboxed installs from a bundle or manifest | Your normal Flatpak workflow |
| Source | Development, testing, or patching | git pull and rebuild |
| System install | Installing to /usr/local from source | sudo make install again |
| Windows portable | Windows 10 and 11, x86_64 or ARM64 | Re-run install.ps1 from the new release |
| macOS | macOS 11 or newer, Apple Silicon or Intel | Re-run install-macos.sh --replace from the new release |
The fastest path on Linux is the versioned release installer: download the tag-pinned script, inspect it, then run it. It selects the matching AppImage, pins the release public key, verifies its SHA-256 checksum and Ed25519 signature, and installs it to ~/.local/bin.
On Windows, download the release's Windows archive for your architecture (OpenBox-x86_64-windows.zip or OpenBox-arm64-windows.zip), extract it, and run the bundled installer at OpenBox\scripts\install.ps1: it verifies the same key pin, checksum, and signature before extracting the portable install to %LOCALAPPDATA%\OpenBox, registering the Start Menu shortcut and the openbox:// handler, and adding the launchers to your user PATH. The full walkthrough is on the Windows page.
Prerequisites
Before you install, confirm your system meets the baseline:
| Requirement | AppImage | Flatpak | Source | Windows | macOS app bundle |
|---|---|---|---|---|---|
| Linux desktop (X11 or Wayland) | Yes | Yes | Yes | Not applicable | Not applicable |
| glibc 2.35 or newer (Ubuntu 22.04 baseline) | Yes | Not applicable | Yes | Not applicable | Not applicable |
| Windows 10 or 11, x86_64 or ARM64 | Not applicable | Not applicable | Not applicable | Yes | Not applicable |
| macOS 11 or newer, Apple Silicon or Intel | Not applicable | Not applicable | Not applicable | Not applicable | Yes |
| WebKitGTK 4.1 for the native window | Bundled | Bundled | Required (libwebkit2gtk-4.1) | Not used | Not used |
| WebView2 runtime for the native window | Not used | Not used | Not used | Required for the native window — bundled on Windows 11 and most Windows 10 systems; falls back to a browser window without it | Not used |
| WKWebView for the native window | Not used | Not used | Not used | Not used | Built in |
| Rust toolchain | Not needed | Not needed | 1.92 or newer (rust-toolchain.toml pins 1.99.1) | Only to build from source | Only to build from source |
| Python | Not required; host python3 3.11+ only for .py v2 plugins | Not required; host python3 3.11+ only for .py v2 plugins | 3.11+ only for OPENBOX_BACKEND=python and .py plugins | 3.11+ only for install.ps1 verification and .py plugins | Not required to run; python3 3.11+ for install-macos.sh and .py plugins |
flatpak + flatpak-builder | Not needed | Required | Not needed | Not needed | Not needed |
git | Not needed | Not needed | Required | Not needed | Not needed |
| FUSE (to mount AppImages) | Required | Not needed | Not needed | Not applicable | Not applicable |
bubblewrap bwrap | Optional (plugins sandboxed when present) | Bundled check | Optional (plugins sandboxed when present) | Not applicable | Not available; plugins need trust or the unsandboxed override |
| Visual Studio Build Tools (C++ workload) | Not needed | Not needed | Not needed | Only to build the native host from source | Not needed |
AppImage
The AppImage is a single executable file that bundles OpenBoxGL 3.0, the native host, and the Rust openbox-server. It does not need to be "installed" system-wide and works on immutable images like SteamOS and Bazzite. The 3.0 builds are 9.7 MiB (x86_64) and 9.0 MiB (aarch64).
Versioned release installer
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=3.0.0
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.sh
VERSION is the current release, 3.0.0. Pin it deliberately only when reproducing a specific build, because security fixes are not backported to older releases (see Security). The install.sh file is itself fetched from that tag, so the download needs a tag either way; dropping the OPENBOX_RELEASE_TAG="v${VERSION}" prefix lets the installer resolve the latest release at run time instead.
The installer needs curl, python3 3.11+, openssl, and sha256sum on PATH: it verifies the release public-key pin, the SHA-256 checksum, and the Ed25519 signature before installing to ~/.local/bin.
To launch OpenBox right after installing, pass --run after the tag-pinned invocation:
OPENBOX_RELEASE_TAG="v${VERSION}" bash install.sh --run
Omit OPENBOX_RELEASE_TAG only when you intentionally want the latest stable release. Install to a different directory with OPENBOX_INSTALL_DIR (e.g. OPENBOX_INSTALL_DIR="$HOME/Applications").
The installer detects x86_64 or aarch64 from uname -m. Packaging and emulation environments can select one explicitly with OPENBOX_ARCH=x86_64 or OPENBOX_ARCH=aarch64.
Manual download
- 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). - Make it executable. Downloads are not executable by default, and a non-executable AppImage reports "Permission denied" when you try to run it:
chmod +x OpenBox-$(uname -m).AppImage
- Run it:
./OpenBox-$(uname -m).AppImage
The first launch starts the Rust server on loopback, writes the per-launch token files into the data directory, and opens the native WebKitGTK window. If WebKitGTK is missing, the launcher prints an install hint and falls back to a chrome-less app window (then your default browser).
Use --web to start the server without a native window:
./OpenBox-x86_64.AppImage --web
--web prints a tokenless loopback URL. Open http://127.0.0.1:<port>/?token=<value> with the server.port and server.token values from the data directory, or send X-OpenBox-Token on API calls.
Flatpak
Install the published bundle, or build from the project's manifest with flatpak-builder:
flatpak install --user --bundle OpenBox-x86_64.flatpak
flatpak run io.openbox.GameLauncher
git clone https://github.com/vindeckyy/OpenBoxGL.git
cd OpenBoxGL
cargo build --release --locked -p openbox-cli
cp target/release/openbox-server .
flatpak-builder --user --install --force-clean build-dir io.openbox.GameLauncher.yml
flatpak run io.openbox.GameLauncher
Download OpenBox-x86_64.flatpak from the release page for the bundle install. The 3.0 Flatpak is 7.1 MiB.
- The manifest uses the GNOME Flatpak runtime (
org.gnome.Platform51) and grants--filesystem=home, so Steam, Heroic, Lutris, and ROM folders under your home directory are readable. - The Flatpak is not updated by OpenBoxGL's built-in updater. Update by installing a new bundle or rebuilding the manifest with the Flatpak workflow you already use.
- Flatpak builds install the same
openboxandopenbox-nativelaunchers;flatpak run io.openbox.GameLauncher --webstarts the loopback server without a native window.
Source / system
Source installs build the Rust server. Install Rust 1.92 or newer (the pinned toolchain is 1.99.1), then:
git clone https://github.com/vindeckyy/OpenBoxGL.git
cd OpenBoxGL
cargo build --release --locked -p openbox-cli
./openbox.sh
./openbox.sh resolves target/release/openbox-server and opens the native window when the host is available. To build the Linux native host:
make native-host
./openbox-native.sh
To start the server without a native window:
./openbox.sh --web
The Python fallback still exists for source checkouts. It requires Python 3.11 or newer and is not the shipped backend:
OPENBOX_BACKEND=python python3 web_app.py
For a system install under /usr/local (override with PREFIX=...):
make build-rust
sudo make install
openbox # Native window (default)
openbox --web # Headless Rust server on loopback
sudo make uninstall # removes everything the target placed
The install target places openbox-server under /usr/local/share/openbox when it has been built. Build it first with make build-rust.
Windows
Windows 10 and 11 on x86_64 and ARM64 are supported through a signed portable install rather than an AppImage. Download the release's OpenBox-x86_64-windows.zip (14.6 MiB) or OpenBox-arm64-windows.zip (13.8 MiB), extract it, and run the bundled installer at OpenBox\scripts\install.ps1; it resolves and pins the release public key, then verifies the archive's SHA-256 checksum and Ed25519 signature before extracting the runtime to %LOCALAPPDATA%\OpenBox\share\openbox:
$Version = '3.0.0'
Invoke-WebRequest -UseBasicParsing -OutFile OpenBox-x86_64-windows.zip `
"https://github.com/vindeckyy/OpenBoxGL/releases/download/v$Version/OpenBox-x86_64-windows.zip"
Expand-Archive OpenBox-x86_64-windows.zip -DestinationPath .
Get-Content .\OpenBox\scripts\install.ps1 # read it before running it
powershell -ExecutionPolicy Bypass -File .\OpenBox\scripts\install.ps1 -Tag "v$Version"
The release also publishes install.ps1 as a standalone asset, but it is the same installer that ships inside the archive, and it needs the release verifier (updates.py) one directory above it. The verifier is the trust anchor for the Ed25519 check, so it is never downloaded on its own — a fetched verifier could be replaced by whoever served it. Run the standalone copy from the extracted release, where updates.py is one directory above it; anywhere else it fails with "The release verifier was not found".
Requirements are Windows PowerShell 5.1, which ships with Windows, and Python 3.11 or newer on PATH for the installer's signature verification. The installer verifies signatures with the Python standard library, so neither curl nor OpenSSL is needed; the in-app update check uses the Rust verifier. The portable runtime itself does not need Python: OpenBox\openbox.cmd launches the bundled openbox-server.exe. The installer keeps the previous tree at share\openbox.previous, registers the Start Menu shortcut and the openbox:// protocol handler, and adds the runtime folder to your user PATH.
The openbox.cmd, openbox.ps1, and openbox-native.ps1 launchers mirror openbox and openbox-native on Linux: openbox opens the native WebView2 window once the host is built and the same UI in a browser app window otherwise, while openbox --web always uses the browser. The launchers resolve openbox-server.exe first (OPENBOX_SERVER_BIN, the install tree, then PATH) and fall back to Python only when OPENBOX_BACKEND=python is set. Library data lives in %LOCALAPPDATA%\openbox-game-launcher.
The release publishes three installers, install.sh, install.ps1, and install-macos.sh, plus verify_release.py and openbox-release.pub. The uninstaller is not a release asset: it ships inside the zip and inside the install tree, so you run it from scripts\uninstall.ps1 under your install directory (for a default install, %LOCALAPPDATA%\OpenBox\share\openbox\scripts\uninstall.ps1) with powershell -ExecutionPolicy Bypass -File; add -InstallDir for a non-default install, or -WhatIf to preview. It removes exactly what the installer created — the install tree and its rollback copy, the user PATH entry, the Start Menu shortcut, and the openbox:// registration — and never touches your library or settings. The Windows page covers installer options, the native host build, deeplinks, updating, the uninstaller, and Windows troubleshooting in full.
macOS
macOS 11 or newer on Apple Silicon or Intel installs from the signed universal app bundle (17.4 MiB). Download install-macos.sh from the release, read it, and run it with the tag pinned:
VERSION=3.0.0
curl --proto '=https' --tlsv1.2 --fail --location \
--output install-macos.sh \
"https://github.com/vindeckyy/OpenBoxGL/releases/download/v${VERSION}/install-macos.sh"
less install-macos.sh
OPENBOX_RELEASE_TAG="v${VERSION}" bash install-macos.sh
The installer verifies the release key, the bundle's SHA-256 checksum, and its Ed25519 signature, then installs OpenBox.app into ~/Applications and links openbox into ~/.local/bin. It needs python3 3.11 or newer on your PATH to run the release verifier. The bundle itself ships the universal openbox-server binary and the WKWebView host with zero bundled Python. The bundle is not notarized, so the first launch asks you to allow it in System Settings > Privacy & Security > Open Anyway. Re-run with --replace to upgrade an existing install. The macOS page covers the native window, updates, saves, what is hidden on macOS, and troubleshooting.
Making an app menu entry
Open Settings and choose Install desktop shortcut (the button is enabled only when OpenBoxGL detects it is running from an AppImage). This writes a .desktop entry under ~/.local/share/applications pointing at the AppImage's current path. If you move the AppImage afterwards, re-run the install shortcut so the entry follows the new location. Desktop integrators such as Gear Lever also work.
On Windows the portable installer performs the equivalent step for you, writing OpenBox.lnk into your Start Menu programs folder and registering the openbox:// handler. If you move the install, re-register it from the install folder:
python -B updates.py install-desktop-entry .\openbox.cmd
Verify your install
- 1Run the entry point from a terminal. It should open the native window showing the three-column workspace.
- 2On first launch with an empty library, the setup dialog (Set up your library) appears.
- 3Settings → About reports the running version, platform, data folder, and whether OpenBox is in its native window or a browser tab. The update status line in Settings shows
· AppImagewhen OpenBox runs from an AppImage. - 4Your data directory (
~/.local/share/openbox-game-launcheron Linux,%LOCALAPPDATA%\openbox-game-launcheron Windows, or~/Library/Application Support/openbox-game-launcheron macOS, unlessOPENBOX_DATA_DIRis set) now containslibrary.json,server.token, andserver.port. - 5
GET /api/v2/versionreports"version": "3.0.0","runtime": "rust","state_schema": 7,"plugin_api_version": 2,"backup_format": 2, and"sync_format": 3.
Optional local configuration
OpenBoxGL loads credentials and HTTP-allowlist values from .env files it discovers: an explicit OPENBOX_ENV_FILE path if set, the data directory and its parent, ~/.env, and ~/.config/openbox-game-launcher/.env — plus, on Windows, %APPDATA%\openbox-game-launcher and %LOCALAPPDATA%\openbox-game-launcher. The current working directory is not searched. A .env file is a credential and HTTP-allowlist file only: the provider credentials, the GitHub token aliases, OPENBOX_ALLOW_HTTP_WEBHOOKS, and OPENBOX_ALLOW_HTTP_GAMEYFIN are read from it, and every other key in the file is dropped silently. The remaining variables — OPENBOX_SERVER_BIN, OPENBOX_BACKEND, OPENBOX_ROOT, OPENBOX_PORT, OPENBOX_MEDIA_ROOTS, OPENBOX_SAFE_MODE, OPENBOX_SNAPSHOT_DEBOUNCE (Python fallback only), OPENBOX_EXECUTABLE, OPENBOX_ENABLE_DMABUF, OPENBOX_WEBKIT_HARDWARE_ACCELERATION, OPENBOX_ENABLE_SQLITE_READ, and the data-directory and host path overrides — are read from the process environment only, never from .env. Each file must be an owner-only regular file (no group or other permission bits; 0o600 is the usual value) and not a symlink. A documented template ships as .env.example.
Secrets and tokens (RetroAchievements, EmuMovies, IGDB, GitHub) are read from these files or from the process environment. Put real secrets in ~/.env or ~/.config/openbox-game-launcher/.env only, never in the repository or in a tracked file.
See Configuration for the full environment contract.
Where installs keep state
All library data, media, backups, themes, and logs live in ~/.local/share/openbox-game-launcher on Linux, or in the OPENBOX_DATA_DIR you set. They are never inside the AppImage file, and updating or deleting the AppImage does not touch your library.
The Windows portable install uses the same layout under %LOCALAPPDATA%\openbox-game-launcher; updating or deleting %LOCALAPPDATA%\OpenBox leaves the library untouched. The macOS app stores its data in ~/Library/Application Support/openbox-game-launcher, and updating or deleting OpenBox.app leaves it untouched.
Troubleshooting
| Problem | Cause / fix |
|---|---|
Permission denied on the AppImage | The file is not executable: chmod +x OpenBox-x86_64.AppImage. |
| AppImage will not mount | The FUSE 2 library is missing on the host. Install libfuse2 on Debian/Ubuntu (libfuse2t64 on Ubuntu 24.04+), fuse-libs on Fedora, or fuse2 on Arch — or run the AppImage with --appimage-extract-and-run to skip FUSE entirely. |
| Window does not open | Run from a terminal and read the printed error. In --web mode, open the printed http://127.0.0.1:PORT/ URL yourself — the printed URL carries no token, so take the value from server.token in the data directory, send it in the X-OpenBox-Token header for API calls, or append it as ?token=<value> in the browser URL. |
Source: openbox-server not found | Build it with cargo build --release --locked -p openbox-cli, or set OPENBOX_SERVER_BIN to its path. The launcher falls back to OPENBOX_BACKEND=python only when you set it. |
Source fallback: python3: command not found or ModuleNotFoundError | The fallback requires Python 3.11+ and must be python3. Packaged builds do not need Python. |
| Flatpak can't read Steam/ROMs | Keep folders under your home directory; the manifest grants --filesystem=home. |
Windows: running scripts is disabled on this system | Run the script with powershell -ExecutionPolicy Bypass -File .\OpenBox\scripts\install.ps1, or set your execution policy for your user. See Windows. |
Windows: No Python 3 interpreter found | Only the installer needs Python. Install Python 3.11+ for install.ps1, or launch the portable copy with OpenBox\openbox.cmd (no Python required). |
| macOS: app cannot be opened | The bundle is ad-hoc signed and not notarized. Allow it in System Settings > Privacy & Security > Open Anyway. |
| Library looks empty after install | Check OPENBOX_DATA_DIR, the server reads a different directory than the one you edited. It must be in the process environment at launch. |
More at Troubleshooting startup and browser.
After installation
Your first launch creates the data directory with an empty library. The window shows the setup dialog (Set up your library) when the library is empty; it opens on a six-step quick path (with the longer optional steps behind an advanced toggle) that walks you through a guided preview-before-commit scan, emulator readiness checks, metadata match review, and initial preferences. The empty library also offers Scan a folder, Connect a game store, and Add one game directly.
- First-time setup: Getting started
- What the interfaces look like and where data lives: Interfaces and data
- Keeping an install current: Updating
- If something does not start: Troubleshooting