Windows

OpenBoxGL runs natively on Windows as of 1.13.0. There is no MSI, no installer wizard, no account, and no license key: the portable installer verifies a signed release, lays the runtime down under %LOCALAPPDATA%\OpenBox, and adds the launchers to your user PATH.

The Windows build is the same Python standard-library application that runs on Linux. The library format, the web UI, the HTTP API, the plugins, and the emulator definitions are identical across platforms, so a library directory moves between Linux and Windows unchanged.

Windows builds are x86_64.

Requirements

The installer itself needs Python, because it uses the same RFC 8032 verifier the in-app updater uses to check the release signature.

Install from a signed release

Download the installer and the release archive from the same tag, then run the installer. The installer pins the release public key, verifies its SHA-256 against a committed anchor, and verifies the archive's .sha256 sidecar and Ed25519 signature before extracting anything.

$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"

Pass -Run to start OpenBox when the install finishes:

.\install.ps1 -Tag "v$Version" -Run

The installer always fetches OpenBox-x86_64-windows.zip, its .sha256, and its .sig from the release tag into a fresh temp directory — placing the files next to install.ps1 yourself has no effect. For a mirrored or offline key, pass -PublicKeyPath instead.

What the installer does

1. 1
   Resolves openbox-release.pub from the release and checks its SHA-256 against the pinned bootstrap anchor. -PublicKeyPath replaces that anchor for mirror or offline installs, and the checksum and signature gates still apply.
2. 2
   Downloads OpenBox-x86_64-windows.zip with its .sha256 and .sig, then fails closed if any check does not match. -Arch accepts x86_64 (or amd64); ARM64 values fail because there is no ARM64 Windows zip.
3. 3
   Extracts the archive, which must contain exactly one top-level folder holding web_app.py.
4. 4
   Moves the runtime to <InstallDir>\share\openbox, keeping any previous install at <InstallDir>\share\openbox.previous.
5. 5
   Registers the Start Menu shortcut and the openbox:// protocol handler for the current user.
6. 6
   Adds the runtime folder to your user PATH unless you pass -NoPathUpdate.

Nothing is extracted before every verification step passes.

Installer options

Uninstall

The release ships the uninstaller inside the archive, at scripts\uninstall.ps1 — it is not published as a standalone release asset, so there is no separate download for it. It is the exact mirror of the installer, and it removes precisely what install.ps1 creates:

• the install tree at <InstallDir>\share\openbox and its openbox.previous rollback copy, dropping the now-empty share\ and bin roots when nothing else lives there;
• the install's entry in your user PATH;
• the OpenBox.lnk Start Menu shortcut;
• the openbox:// protocol registration at HKCU\Software\Classes\openbox.

Run the copy inside your install, using the same -InstallDir you installed with (omit it for a default install, which is %LOCALAPPDATA%\OpenBox):

# Preview first (recommended)
powershell -ExecutionPolicy Bypass `
  -File "$env:LOCALAPPDATA\OpenBox\share\openbox\scripts\uninstall.ps1" -WhatIf

# Then actually remove
powershell -ExecutionPolicy Bypass `
  -File "$env:LOCALAPPDATA\OpenBox\share\openbox\scripts\uninstall.ps1"

# Non-default install directory
powershell -ExecutionPolicy Bypass `
  -File "D:\Apps\OpenBox\share\openbox\scripts\uninstall.ps1" -InstallDir "D:\Apps\OpenBox"

It runs on Windows PowerShell 5.1 with the standard library only, and takes one optional argument, -InstallDir <path>, if the installer used something other than %LOCALAPPDATA%\OpenBox (it also honors OPENBOX_INSTALL_DIR). The -WhatIf example above previews the whole thing before anything is removed.

To remove an install made before 1.15.0, or to do it by hand, the four steps the script performs are: delete %LOCALAPPDATA%\OpenBox (including share\openbox.previous), remove the runtime folder from your user PATH in Settings → System → About → Advanced system settings → Environment Variables, delete the OpenBox.lnk shortcut from your Start Menu programs folder, and delete the HKEY_CURRENT_USER\Software\Classes\openbox registry key.

Launching OpenBox

The install contains three launchers, mirroring the openbox and openbox-native scripts on Linux:

openbox                 # native window when built, otherwise the browser app window
openbox --web           # always use the loopback web UI in your default browser
openbox-native          # run the native host explicitly

Both scripts accept the same flags as the Linux launchers and forward them to the application. The launchers find the runtime through OPENBOX_SHARE, then their own folder, then %LOCALAPPDATA%\OpenBox\share\openbox, and find Python as python.exe or py.exe on PATH unless OPENBOX_PYTHON is set.

--web prints a http://127.0.0.1:PORT/?token=... URL. The token is per-launch and is written to the data directory, so the window you opened can always be re-opened from the terminal output if a browser does not appear.

The native window

The native window is a WebView2 host that renders the same UI over the loopback server. It is the Windows counterpart of the WebKitGTK host: it owns the Python server's lifetime, exposes the same window.openboxNative bridge the page already speaks, remembers window geometry, provides the tray icon and minimize-to-tray, handles openbox:// deeplinks, allows one instance per data directory (a second launch focuses the running window), shuts the server down gracefully when the window closes, and force-kills the process tree through a job object if it does not exit.

The released portable install ships this host compiled, so the native window opens as installed — no toolchain, no build step. Building it yourself is only needed when you run from a source checkout (a git clone has no native_host.exe beside web_app.py), or when you want to change the host yourself:

powershell -ExecutionPolicy Bypass -File scripts\build_native_host_windows.ps1

The script builds native_host.exe next to web_app.py from native_host_win.c and embeds openbox.ico as its icon. It needs the MSVC toolchain, which means Visual Studio Build Tools with the C++ workload; the WebView2 SDK is taken from your NuGet cache when present and downloaded from nuget.org otherwise. The loader is linked statically, so the resulting binary needs no extra DLL. Release and CI builds run this same script, and the release refuses to publish a zip that does not contain the host.

Once native_host.exe is next to web_app.py, every launcher uses it automatically. Set OPENBOX_NATIVE_HOST to point at a host binary somewhere else.

If the host is missing (source checkout, or a failed build), the launchers print a warning and open the same UI in a browser app window. Nothing else changes: your library, settings, and data directory are the same either way.

Which window am I using?

Settings → About (v1.15.0) answers the question the fallback above raises. It shows four things, read from the same host report the window itself uses:

The same four values are available over the API through the native capabilities response, which reports version, platform, and data_dir alongside its existing fields. See API local administrator.

Where your data lives

Set OPENBOX_DATA_DIR to move the library, which is read before the .env bootstrap, so it must be in the process environment at launch. This is the same contract the Linux builds use; only the default location differs. See Configuration for the full environment list.

Updating

The built-in updater understands the Windows portable install. It verifies the release key the same way the installer does — pinned key anchor, SHA-256 checksum, Ed25519 signature, with the same stdlib-only implementation, so Windows needs neither curl nor OpenSSL — then downloads OpenBox-x86_64-windows.zip, extracts it, and stages the swap.

Because a running install cannot be replaced in place, the swap happens after OpenBox exits: the old tree is moved to share\openbox.previous, the staged tree takes its place, and the app asks you to restart. Your data directory is never part of the swap. See Updating for the general update flow.

Manual update: download the newer OpenBox-x86_64-windows.zip and run that release's install.ps1, which keeps the previous tree for rollback.

Emulators and games on Windows

Emulator support is not Linux-specific. Every bundled emulator definition carries its Windows executable name, so adapter detection, resume-state capture, and Launch Doctor work with Windows builds of Dolphin, RetroArch, PCSX2, RPCS3, Cemu, melonDS, PPSSPP, Vita3K, xemu, Xenia, and the others the matrix lists. See Emulators and launching and the Hardware matrix.

Windows games launch through the game's own executable or through an emulator, exactly as on Linux. Controller support, save-state capture, screenshots, and portable library paths behave identically.

Troubleshooting

More at Troubleshooting startup and browser.

What stays Linux-only

Windows runs the application, the library, the emulators, and the native window. The distribution-level integrations remain Linux:

• AppImage and Flatpak packaging, and the built-in updater's AppImage path.
• gamescope presets and Steam Deck / handheld tuning, including Game Mode.
• XDG desktop entries, sudo make install, and distro packaging.
• Flathub-aware emulator management.

See Steam Deck for the handheld workflow and Compare for the platform matrix.

Related pages

• Installation
• Downloads
• Updating
• Configuration
• Getting started