Configuration

OpenBoxGL reads configuration from three places, in order: the process environment, discovered .env files, and persisted application settings (the Settings dialog). This page documents each source, the exact variables, and the validation limits applied when settings are saved.

Configuration sources

A .env file sets an environment variable only when that variable is not already set, so the process environment always wins. Unreadable or non-UTF-8 .env files are skipped silently; an optional .env must never abort startup.

.env discovery order

env_config.discover_env_files checks these roots in order and loads every .env found:

1. An explicit OPENBOX_ENV_FILE path, if set (read before the extra roots).
2. The data directory (the extra root passed to bootstrap_env).
3. The parent of the data directory.
4. Your home directory (~/.env).
5. ~/.config/openbox-game-launcher/.env.

The current working directory and the application directory are not searched. Each .env file must be an owner-only regular file (mode 0o600, no group or other permission bits), must not be a symlink, and must be under 1 MiB; anything else is skipped silently. Windows has no POSIX mode bits, so there the check rejects reparse points instead and otherwise relies on the per-user profile ACL — keep .env inside your own profile directory.

Values already in the environment are never overridden by .env. The template lives at .env.example in the repository. Put real secrets in ~/.env or ~/.config/openbox-game-launcher/.env only, never in a tracked file.

Environment variables

Data and process behavior

Windows launchers

The Windows runtime tree ships three entry points:

Python is located as python.exe or py.exe on PATH, or through OPENBOX_PYTHON; OPENBOX_SHARE points the launchers at the runtime directory. native_host.exe ships compiled in the released portable install; rebuilding it from a source checkout is powershell -File scripts/build_native_host_windows.ps1 (MSVC toolchain; WebView2 SDK from the NuGet cache or nuget.org), and without native_host.exe the launchers open the same UI in a browser app window. See Windows for the install layout.

Credentials (all optional)

Each credential lookup checks the aliases in order using env_value() from env_config.py, it iterates through the listed names for a variable and uses the first non-empty value found. If an empty string is returned for any required variable, the route returns a specific 400 error naming exactly which variable is missing. For example, IGDB requires both IGDB_CLIENT_ID and IGDB_CLIENT_SECRET; without either the IGDB routes return 400 {"error":"Set IGDB_CLIENT_ID and IGDB_CLIENT_SECRET in ~/.env to use IGDB."}. Without RetroAchievements credentials, the /api/ra/* routes return 400 {"error":"Configure RetroAchievements first."}.

Credentials supplied through the Settings dialog are persisted in the data directory (retroachievements.json, emumovies.json, settings.json for Gameyfin) with owner-only permissions (0o600 via secure_text_write). The API and diagnostic log redact the values, but the files themselves are plaintext. Windows has no POSIX mode bits, so there these files rely on the per-user profile ACL instead.

Persisted settings

The Settings dialog saves into library.json under settings. The save handler (SettingsHandlers._save_settings_locked in handlers/settings.py:646) validates each field before committing; an invalid value aborts the whole save with a 400 error. Keys must exist in the settings_schema.py registry: unknown keys are dropped with a diagnostic log warning rather than persisted. GET /api/settings returns the public projection of the settings, which is a curated subset of the registry (a few internal and separately-owned keys are not part of it). Notable validated limits:

Two naming details worth knowing:

• bigbox_shutdown_commands is misnamed: the commands run when Big Box is entered, not when it is left.
• attract_mode_seconds is the screensaver delay the Big Box screensaver actually reads; it falls back to screensaver_seconds when unset, and the Settings dialog keeps both fields with the same fallback.

Partial saves merge with existing settings: keys you omit are preserved, and concurrent partial saves of different keys do not lose updates (covered by the API sweep tests). An empty gameyfin_password in a save leaves the stored password unchanged.

Values consumed at startup

These are read once during process startup and require a restart to change:

• OPENBOX_DATA_DIR (data directory and state store path)
• server.token / server.port (per-launch, deleted on exit)
• .env bootstrap (performed once per process)
• startup_commands (run after the server binds, via run_configured_commands)
• Profile merging from emulator definition packs (merge_profiles_from_definitions) at startup

shutdown_commands run on graceful exit. Both command lists execute with shlex.split and a new session; failures are logged and skipped, never fatal.

Security notes

• Public examples must use placeholders. Never commit .env, server.token, retroachievements.json, emumovies.json, or library exports.
• Keep server.token, provider credentials, and webhook secrets private. The diagnostic log redacts values matching token/password/secret/API-key/authorization patterns, but a .env file is plaintext.
• Restart OpenBoxGL after changing values consumed at process startup.

The authoritative sources are .env.example, env_config.py, handlers/settings.py, settings_schema.py, and the Settings dialog.