// 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

PackageBest forUpdates
AppImageDesktop, Steam Deck, handhelds, immutable systemsBuilt-in verified updater
FlatpakSandboxed installs from a bundle or manifestYour normal Flatpak workflow
SourceDevelopment, testing, or patchinggit pull and rebuild
System installInstalling to /usr/local from sourcesudo make install again
Windows portableWindows 10 and 11, x86_64 or ARM64Re-run install.ps1 from the new release
macOSmacOS 11 or newer, Apple Silicon or IntelRe-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:

RequirementAppImageFlatpakSourceWindowsmacOS app bundle
Linux desktop (X11 or Wayland)YesYesYesNot applicableNot applicable
glibc 2.35 or newer (Ubuntu 22.04 baseline)YesNot applicableYesNot applicableNot applicable
Windows 10 or 11, x86_64 or ARM64Not applicableNot applicableNot applicableYesNot applicable
macOS 11 or newer, Apple Silicon or IntelNot applicableNot applicableNot applicableNot applicableYes
WebKitGTK 4.1 for the native windowBundledBundledRequired (libwebkit2gtk-4.1)Not usedNot used
WebView2 runtime for the native windowNot usedNot usedNot usedRequired for the native window — bundled on Windows 11 and most Windows 10 systems; falls back to a browser window without itNot used
WKWebView for the native windowNot usedNot usedNot usedNot usedBuilt in
Rust toolchainNot neededNot needed1.92 or newer (rust-toolchain.toml pins 1.99.1)Only to build from sourceOnly to build from source
PythonNot required; host python3 3.11+ only for .py v2 pluginsNot required; host python3 3.11+ only for .py v2 plugins3.11+ only for OPENBOX_BACKEND=python and .py plugins3.11+ only for install.ps1 verification and .py pluginsNot required to run; python3 3.11+ for install-macos.sh and .py plugins
flatpak + flatpak-builderNot neededRequiredNot neededNot neededNot needed
gitNot neededNot neededRequiredNot neededNot needed
FUSE (to mount AppImages)RequiredNot neededNot neededNot applicableNot applicable
bubblewrap bwrapOptional (plugins sandboxed when present)Bundled checkOptional (plugins sandboxed when present)Not applicableNot available; plugins need trust or the unsandboxed override
Visual Studio Build Tools (C++ workload)Not neededNot neededNot neededOnly to build the native host from sourceNot 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

  1. 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).
  2. 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
  1. 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.Platform 51) 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 openbox and openbox-native launchers; flatpak run io.openbox.GameLauncher --web starts 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

  1. 1
    Run the entry point from a terminal. It should open the native window showing the three-column workspace.
  2. 2
    On first launch with an empty library, the setup dialog (Set up your library) appears.
  3. 3
    Settings → 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 · AppImage when OpenBox runs from an AppImage.
  4. 4
    Your data directory (~/.local/share/openbox-game-launcher on Linux, %LOCALAPPDATA%\openbox-game-launcher on Windows, or ~/Library/Application Support/openbox-game-launcher on macOS, unless OPENBOX_DATA_DIR is set) now contains library.json, server.token, and server.port.
  5. 5
    GET /api/v2/version reports "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

ProblemCause / fix
Permission denied on the AppImageThe file is not executable: chmod +x OpenBox-x86_64.AppImage.
AppImage will not mountThe 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 openRun 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 foundBuild 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 ModuleNotFoundErrorThe fallback requires Python 3.11+ and must be python3. Packaged builds do not need Python.
Flatpak can't read Steam/ROMsKeep folders under your home directory; the manifest grants --filesystem=home.
Windows: running scripts is disabled on this systemRun 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 foundOnly 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 openedThe bundle is ad-hoc signed and not notarized. Allow it in System Settings > Privacy & Security > Open Anyway.
Library looks empty after installCheck 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.