Installation

OpenBoxGL runs on Linux and, since 1.13.0, natively on Windows. On Linux the AppImage is the recommended path with Python 3.10+ for source installs: it bundles its own Python runtime, so you never depend on system Python versions or library packages. On Windows the signed portable installer is the supported path; it is covered in full on the Windows page.

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

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 install.ps1, inspect it, and run it: 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.

Only the AppImage and the Windows portable install receive the built-in updater. Flatpak, source, and system installs follow their own package or source workflow; see Updating.

Prerequisites

Before you install, confirm your system meets the baseline:

VERSION=1.15.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

OPENBOX_RELEASE_TAG="v${VERSION}" bash install.sh --run

chmod +x OpenBox-$(uname -m).AppImage

./OpenBox-$(uname -m).AppImage

./OpenBox-x86_64.AppImage --web

flatpak install --bundle OpenBox-x86_64.flatpak
flatpak run io.openbox.GameLauncher

git clone https://github.com/vindeckyy/OpenBoxGL.git
cd OpenBoxGL
flatpak-builder --user --install --force-clean build-dir io.openbox.GameLauncher.yml
flatpak run io.openbox.GameLauncher

git clone https://github.com/vindeckyy/OpenBoxGL.git
cd OpenBoxGL
python3 web_app.py

sudo make install
openbox     # Native window (default)
openbox --web  # Web UI (development)
sudo make uninstall  # removes everything the target placed

Windows

Windows 10 and 11 on x86_64 are supported since 1.13.0, through a signed portable install rather than an AppImage. Download the release's install.ps1 and run it; 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 = '1.15.0'
Invoke-WebRequest -UseBasicParsing -OutFile install.ps1 `
  "https://github.com/vindeckyy/OpenBoxGL/releases/download/v$Version/install.ps1"
.\install.ps1 -Tag "v$Version"

Requirements are Windows PowerShell 5.1, which ships with Windows, and Python 3.10 or newer on PATH. The installer and the built-in updater verify signatures with the Python standard library, so neither curl nor OpenSSL is needed. 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. Library data lives in %LOCALAPPDATA%\openbox-game-launcher.

The release publishes only the two installers, install.sh and install.ps1, as standalone assets — the uninstaller is not one of them. 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.

Making an app menu entry

Open Settings and choose Install desktop shortcut (the button appears 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 Library Setup Center appears.
3. 3
   Settings → About (or GET /api/settings with the token) reports the running version and whether it is an AppImage.
4. 4
   Your data directory (~/.local/share/openbox-game-launcher unless OPENBOX_DATA_DIR is set) now contains library.json, server.token, and server.port.

Optional local configuration

OpenBoxGL loads optional credentials and settings 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. The current working directory is not searched. Each file must be an owner-only regular file (mode 0o600, no group or other permission bits) 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 (or the OPENBOX_DATA_DIR you set), never inside the AppImage file. 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.

Troubleshooting

More at Troubleshooting startup and browser.

After installation

Your first launch creates the data directory with an empty library. The window shows the Library Setup Center when the library is empty; it walks you through a guided preview-before-commit scan, emulator readiness checks, metadata match review, and initial preferences.

• First-time setup: Getting started
• What the interfaces look like and where data lives: Interfaces and data
• Keeping an AppImage install current: Updating
• If something does not start: Troubleshooting

Related pages

• Getting started
• Interfaces and data
• Updating