// OPENBOX DOCS

Installation

Install OpenBoxGL on Linux with AppImage, Flatpak, or source.

OpenBoxGL runs on Linux with Python 3.10+ for source installs. AppImage is the recommended path: it bundles its own Python runtime, so you never depend on system Python versions or library packages.

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 manifest	Your normal Flatpak workflow
Source	Development, testing, or patching	`git pull` and re-run
System install	Installing to `/usr/local` from source	`sudo make install` again

The fastest path is the one-liner install: curl ... | bash downloads the latest AppImage, verifies its checksum, and installs it to ~/.local/bin.

Only the AppImage receives 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:

Requirement	AppImage	Flatpak	Source
Linux desktop (X11 or Wayland)	Yes	Yes	Yes
A browser for the Web UI	Yes	Yes	Yes
Python	Bundled	Bundled	3.10+
`flatpak` + `flatpak-builder`	Not needed	Required	Not needed
`git`	Not needed	Not needed	Required
FUSE (to mount AppImages)	Required	Not needed	Not needed

AppImage

The AppImage is a single executable file that bundles OpenBoxGL, Python, and its dependencies. It does not need to be "installed" system-wide and works on immutable images like SteamOS and Bazzite.

One-liner install

Download the latest AppImage, verify its SHA-256 checksum, and install it to ~/.local/bin with a single command:

curl -fsSL https://raw.githubusercontent.com/vindeckyy/OpenBoxGL/master/scripts/install.sh | bash

To also launch OpenBox right after installing:

curl -fsSL https://raw.githubusercontent.com/vindeckyy/OpenBoxGL/master/scripts/install.sh | bash -s -- --run

The script resolves the latest release automatically from GitHub, checks the AppImage against its published SHA-256 before installing, and adds a friendly openbox launcher. Install to a different directory with OPENBOX_INSTALL_DIR (e.g. OPENBOX_INSTALL_DIR="$HOME/Applications").

Manual download

Download the latest release from GitHub Releases. The file is named OpenBox-x86_64.AppImage.
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-x86_64.AppImage

Run it:

./OpenBox-x86_64.AppImage

The first launch starts the local server, writes the per-launch token files into the data directory, and opens the UI in a chrome-less app window by default (falling back to your default browser) on http://127.0.0.1:PORT/?token=.... If the browser does not open, run from a terminal and copy the printed URL into a browser.

Use --native for the lightweight Tk interface instead of the Web UI:

./OpenBox-x86_64.AppImage --native

The Tk interface shares the same library data as the Web UI, so you can switch between them freely.

Flatpak

Build and install the Flatpak from the project's manifest with flatpak-builder:

flatpak-builder --user --install --force-clean build-dir io.openbox.GameLauncher.yml
flatpak run io.openbox.GameLauncher

The manifest (the flatpak module) uses the FreeDesktop runtime and grants --filesystem=home, so Steam, Heroic, Lutris, and ROM folders under your home directory are readable.
Flatpak builds install the same openbox and openbox-native launchers; flatpak run io.openbox.GameLauncher --native starts the Tk interface.
The Flatpak is not updated by OpenBoxGL's built-in updater (it only understands the AppImage). Update by rebuilding the manifest or using the Flatpak workflow you already have for local builds.

Source / system

Source installs are the fastest way to run the current code, and they need the least tooling:

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

Requirements: Python 3.10 or newer on a Linux system with standard desktop tooling. No third-party Python packages are required; the application uses the standard library.

The Web UI starts and opens your browser. python3 openbox.py starts the Tk interface instead.

For a system install under /usr/local (override with PREFIX=...):

sudo make install
openbox          # Web UI
openbox-native   # Native UI
sudo make uninstall   # removes everything the target placed

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.

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.

Verify your install

1
Run the entry point from a terminal. It should print a line like http://127.0.0.1:PORT/?token=... and open your browser.
2
The browser shows the three-column workspace with an empty cover grid. On first launch with an empty library, the welcome wizard appears.
3
Settings → About (or GET /api/settings with the token) reports the running version and whether it is an AppImage.
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: the current directory, the project directory, your home directory, and ~/.config/openbox-game-launcher. 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 the AppImage keeps 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.

Troubleshooting

Problem	Cause / fix
`Permission denied` on the AppImage	The file is not executable: `chmod +x OpenBox-x86_64.AppImage`.
AppImage will not mount	FUSE is missing on the host. Install `fuse` (or `fuse2` on newer distros).
Browser does not open	Run from a terminal and open the printed `http://127.0.0.1:PORT/?token=...` URL yourself.
Source: `python3: command not found` or `ModuleNotFoundError`	Python 3.10+ is required and must be `python3`. On some distros install `python3` and use `python3 web_app.py`.
Flatpak can't read Steam/ROMs	Keep folders under your home directory; the manifest grants `--filesystem=home`.
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 Web UI shows the welcome wizard when the library is empty; it walks you through a folder import, a Steam import, metadata syncing, and settings.

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