// OPENBOX DOCS
Configuration
Configure environment values, local state, and application settings.
OpenBoxGL reads configuration from three places: the process environment, discovered .env files, and persisted application settings (the Settings dialog). A .env file is a credential and HTTP-allowlist file only — it never carries general settings. This page documents each source, the exact variables, and the validation limits applied when settings are saved.
Configuration sources
| Source | When it is read | Precedence |
|---|---|---|
| Process environment | At startup and on demand (os.environ) | Highest for every variable it defines |
Discovered .env files | bootstrap_env at Web UI startup, lazily before some lookups | Never overrides an existing environment value |
| Persisted settings | library.json -> settings | Provider-specific (see below); the only store for UI settings |
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.
A .env file is a credential and HTTP-allowlist file only. openbox-io/src/env_config.rs loads just the names in ENV_KEYS: the provider credentials, the GitHub token aliases, OPENBOX_ALLOW_HTTP_WEBHOOKS, and OPENBOX_ALLOW_HTTP_GAMEYFIN. Every other key in the file is dropped silently, so .env cannot carry general settings.
Credential precedence
Precedence is per provider, not one global order:
| Provider | Order |
|---|---|
| RetroAchievements | retroachievements.json in the data directory, then the environment |
| EmuMovies | emumovies.json in the data directory, then the environment |
| Steam | <data>/steam.json wins per field; STEAM_API_KEY / STEAM_ID only fill the values the file does not have |
| IGDB, ScreenScraper, SteamGridDB | Environment only |
| Gameyfin | Settings only (library.json); no environment variables |
.env discovery order
openbox-io checks these roots in order and loads every .env found:
- An explicit
OPENBOX_ENV_FILEpath, if set (read before the extra roots). - The data directory (the extra root passed to
bootstrap_env). - The parent of the data directory.
- Your home directory (
~/.env). ~/.config/openbox-game-launcher/.env.- On Windows only,
%APPDATA%\openbox-game-launcherand%LOCALAPPDATA%\openbox-game-launcher.
The current working directory and the application directory are not searched. Each .env file must be an owner-only regular file (no group or other permission bits; 0o600 is the usual value), 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. Only the allowlisted keys are read, so a key in the file that is not in ENV_KEYS is ignored — a value placed in .env can look configured while the application never sees it.
Environment variables
Data and process behavior
| Variable | Meaning |
|---|---|
OPENBOX_DATA_DIR | Data directory. Read at startup, before .env bootstrap; must be exported in the shell, desktop entry, or systemd unit before launch. Defaults to ~/.local/share/openbox-game-launcher on Linux, %LOCALAPPDATA%\openbox-game-launcher on Windows, and ~/Library/Application Support/openbox-game-launcher on macOS. When no home directory can be determined, it falls back to openbox-game-launcher inside the current working directory. |
OPENBOX_SERVER_BIN | Explicit path to the openbox-server / openbox-server.exe binary. The launchers and native hosts check this first, then the bundle/share location, then target/release, then PATH. |
OPENBOX_BACKEND | Set to python to run the legacy web_app.py backend instead of Rust. The default is rust. |
OPENBOX_ROOT | Application asset/share root (index.html, static/, locales/, themes/, emulator_defs/, plugin_runner_v2.py). |
OPENBOX_PORT | Bind a specific 127.0.0.1 port instead of an ephemeral one (0, default). |
OPENBOX_SAFE_MODE | Any non-empty value (conventionally 1) disables plugin execution and the webhook dispatcher for the whole process. Exposed as settings.safe_mode. Process environment only (not .env). |
APPIMAGE | Set automatically when running from an AppImage; the Linux updater refuses to install without it. Exposed as settings.appimage. The 3.0 Rust server implements the verified install step for the AppImage only; Windows and macOS use their release installers. |
OPENBOX_ENV_FILE | Explicit path to a single .env file, checked first before the data-directory roots. Read directly from the process environment; must point at an owner-only regular file (not a symlink) or it is skipped. |
OPENBOX_ALLOW_HTTP_WEBHOOKS | Set to 1 to allow plain-HTTP webhook URLs. Required only for trusted local test targets; HTTPS is the default and safer. |
OPENBOX_ALLOW_HTTP_GAMEYFIN | Set to 1 to allow plain-HTTP Gameyfin URLs. HTTPS is the default; loopback (localhost) addresses are always allowed. |
OPENBOX_ALLOW_UNSANDBOXED_PLUGINS | Set to 1 in the process shell to allow unsandboxed plugin execution. The sandbox is disabled entirely whenever this is set, even when bubblewrap is available. Read directly from the process environment (not .env; it is not in ENV_KEYS). |
OPENBOX_MEDIA_ROOTS | Colon-separated list (os.pathsep) of additional absolute directories approved for scanning and media storage. The built-in <data>/media root counts toward the total, so at most 31 additional roots can be added. Process environment only (not .env). |
OPENBOX_EXECUTABLE | Optional explicit path to the emulator/launcher executable recorded when importing Steam titles for Steam Bridge. Read from the process environment at scan time; when unset, the importer uses the Steam-reported executable. Process environment only (not .env). |
OPENBOX_ENABLE_DMABUF | Set to 1 to enable WebKitGTK DMA-BUF rendering in the Linux native window. Disabled by default to prevent silent blank windows on AMD GPUs (including Steam Deck). Windows uses WebView2 instead and ignores this. Process environment only (not .env). |
OPENBOX_WEBKIT_HARDWARE_ACCELERATION | WebKitGTK hardware acceleration policy in the Linux native window (always or on-demand; default is on-demand). Process environment only (not .env). |
OPENBOX_SNAPSHOT_DEBOUNCE | Python fallback only: debounce delay in seconds (float) for background library state snapshot writes (defaults to 0.0). The Rust openbox-server constructs its store with a zero debounce, so this variable has no effect there. Process environment only (not .env). |
OPENBOX_INSTALL_DIR | Custom installation directory used by install.sh (defaults to ~/.local/bin). On Windows the same variable, or install.ps1 -InstallDir, defaults to %LOCALAPPDATA%\OpenBox; the runtime lands in <InstallDir>\share\openbox and the previous tree is kept at <InstallDir>\share\openbox.previous. |
OPENBOX_RELEASE_TAG | Pins a specific GitHub release tag (e.g. v3.0.0) during install.sh execution. |
OPENBOX_PYTHON | Python fallback/plugin override: path to the interpreter used by web_app.py and .py v2 plugins (defaults to python3; on Windows the launchers locate python.exe or py.exe on PATH unless this is set). The Rust server does not use it. |
OPENBOX_WEB_APP | Python fallback only: path to web_app.py used when OPENBOX_BACKEND=python or no openbox-server binary is found. |
OPENBOX_NATIVE_HOST | Path override for the native host binary used by openbox-native.sh (defaults to native_host beside the app). On Windows it overrides the native_host.exe binary that openbox-native.ps1 runs. |
OPENBOX_SHARE | Runtime directory override used by the Windows launchers (openbox.ps1, openbox-native.ps1) to point at the extracted runtime tree. |
OPENBOX_BUNDLED_LIB_PATH | LD_LIBRARY_PATH value used by the AppImage wrapper for bundled libraries. |
OPENBOX_ARCH | Overrides uname -m architecture detection in install.sh and build_appimage.sh (x86_64 or aarch64). |
OPENBOX_UPDATE_INFORMATION | zsync update-metadata line embedded by build_appimage.sh for the verified updater (packaging-time, not user-facing). |
OPENBOX_RELEASE_BASE | Base URL the release assets are served from, read by scripts/install.ps1 (or pass -ReleaseBase). Overrides the default GitHub release download host. |
OPENBOX_ENABLE_SQLITE_READ | Set to 1 to enable the SQLite read model (crates/openbox-store/src/sqlite_readmodel.rs) for accelerated search and facets. The Rust build uses bundled rusqlite with FTS5. JSON remains the source of truth; SQLite is a read-only projection. Release evidence covers up to 50,000 games on the Rust backend. The read model self-enables at 5,000+ games; an explicit 0/false/no opt-out is never overridden. Process environment only (not .env). |
Windows launchers
The Windows runtime tree ships three entry points:
| Entry point | What it does |
|---|---|
openbox.cmd | Double-clickable wrapper |
openbox.ps1 | Runs the ladder: the native WebView2 window first, the browser app window second. --web forces the browser app window. |
openbox-native.ps1 | Runs native_host.exe, or falls back when it is absent |
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 or no server binary exists. Python, when needed, 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)
| Variable | Used by | Aliases |
|---|---|---|
RETROACHIEVEMENTS_USERNAME | RetroAchievements matching and progress | RA_USERNAME, OPENBOX_RA_USERNAME |
RETROACHIEVEMENTS_API_KEY | RetroAchievements web API | RA_API_KEY, RETROACHIEVEMENTS_KEY, OPENBOX_RA_API_KEY |
EMUMOVIES_USERNAME | EmuMovies media downloads | OPENBOX_EMUMOVIES_USERNAME |
EMUMOVIES_PASSWORD | EmuMovies media downloads | OPENBOX_EMUMOVIES_PASSWORD |
GITHUB_TOKEN | GitHub release API rate limit for update checks (GITHUB_TOKEN, GH_TOKEN, OPENBOX_GITHUB_TOKEN all accepted) | GH_TOKEN, OPENBOX_GITHUB_TOKEN |
IGDB_CLIENT_ID | IGDB metadata provider (Twitch developer app) | , |
IGDB_CLIENT_SECRET | IGDB metadata provider (Twitch developer app) | , |
STEAMGRIDDB_API_KEY | SteamGridDB artwork provider: search, apply, and bulk matching | OPENBOX_STEAMGRIDDB_API_KEY |
SCREENSCRAPER_USER | ScreenScraper per-ROM-hash scraping (required for that provider) | OPENBOX_SCREENSCRAPER_USER |
SCREENSCRAPER_PASSWORD | ScreenScraper per-ROM-hash scraping (required for that provider) | OPENBOX_SCREENSCRAPER_PASSWORD |
SCREENSCRAPER_DEV_ID | ScreenScraper developer credentials (required for that provider; the API refuses lookups without them) | OPENBOX_SCREENSCRAPER_DEV_ID |
SCREENSCRAPER_DEV_PASSWORD | ScreenScraper developer credentials (required for that provider) | OPENBOX_SCREENSCRAPER_DEV_PASSWORD |
STEAM_API_KEY | Steam Web API key for achievement and playtime import. Process environment only (not .env). | |
STEAM_ID | Steam ID (64-bit account id) for achievement and playtime import. Process environment only (not .env). |
Most credential lookups check the aliases in order using the Rust env_config resolver: it iterates through the listed names and uses the first non-empty value found. Steam's two values work the other way round: <data>/steam.json (mode 0o600) wins per field, and STEAM_API_KEY / STEAM_ID only fill the values the file does not have. Neither name is in ENV_KEYS or in .env.example, so a value placed in .env is silently dropped — export it in the process environment instead. 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/v2/ra/* routes return 400 {"error":"Configure RetroAchievements first."}.
Credentials supplied through the Settings dialog are persisted in the data directory with owner-only permissions (0o600). RetroAchievements and EmuMovies keep their own files (retroachievements.json, emumovies.json); the Gameyfin password is stored in the library settings inside library.json, which is written with mode 0o600. A settings.json file only ever appears as an archive member inside a backup. 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 (crates/openbox-http/src/handlers/settings.rs) validates each field it normalizes before committing; a value that fails validation aborts the whole save with a 400 error. Many fields are normalized rather than rejected, though: spinner_sensitivity and obs_websocket_timeout are clamped to their range, locale and list_sort_dir are truncated, attract_mode_seconds is only coerced to an integer, and the webhook attempt count and timeout are cast to an integer at save time and clamped only at delivery. Keys must exist in the KNOWN_SETTINGS registry (crates/openbox-core/src/settings.rs, mirrored by settings_schema.py for the Python fallback): unknown keys are dropped with a diagnostic log warning rather than persisted. GET /api/v2/settings returns the projection built by public_settings in crates/openbox-http/src/handlers/projection.rs, not every registry key. The projection omits internal keys such as webhooks, party_queue, health_rescan, list_sort, and the scrape_* keys; gameyfin_password and obs_websocket_password are never returned. Notable validated limits:
| Setting | Default | Validation |
|---|---|---|
watch_folders | [] | List of at most 50 absolute, existing directories; duplicates removed |
screensaver_seconds | 90 | 0 (off) or between 30 and 3600; values 1-29 are rejected |
controller_map | {} | Actions limited to play, back, favorite, random, page_left, page_right, pause, menu; button numbers 0-31 |
gamescope_preset | "" | Selected gamescope preset name (one of: deck, deck_hd, 1080p, 1440p, 4k, integer, stretch, borderless, or a custom preset name). Empty string = no preset. (v1.7.2+) |
mangohud_enabled | false | Boolean; when true, MANGOHUD=1 is set on game launch to enable the MangoHud performance overlay. (v1.7.2+) |
gamescope_custom_presets | [] | Up to 16 user-defined gamescope presets (unique names, bounded integer args). A custom name shadows a stock preset; a per-game gamescope_preset override wins over the global choice. (v1.8.0+) |
list_sort | "title" | List-view sort column key (e.g. title, rating). (v1.8.0+) |
list_sort_dir | "" | List-view sort direction. The known values are "" (ascending) and "reversed"; the value is truncated to 10 characters but its membership is not validated. (v1.8.0+) |
show_insights | true | Boolean; toggles the Play Insights panel in the library pane. (v1.8.0+) |
locale | "en" | Interface language code. The known languages are en, es, de, fr, and pt; the value is truncated to 5 characters but its membership is not validated. (v1.7.2+) |
progress_automation_enabled | false | Boolean; enables/disables automatic progress changes |
progress_automation_play_minutes | 30 | 0 to 100,000, minutes before marking Playing |
progress_automation_idle_days | 30 | 0 to 3,650, days before marking Paused |
progress_on_first_play | "Playing" | Must be a known progress status |
welcome_completed | false | Boolean, suppresses opening the Library Setup Center on empty library launch |
backlog_progress_suggest | true | Boolean; kill switch for the one-time "Playing?" suggestion offered when launching an unplayed game (v1.14.0+) |
image_group | "cover" | One of cover, background, screenshot, clear_logo, fanart, banner, icon, box_back, box_spine, box_3d, title_screen, cart_front, cart_back, disc, advertisement, manual |
badge_visibility | favorite, installed, saves, documents, progress, storefront, achievements, rating | Subset of favorite, installed, missing_media, saves, documents, versions, storefront, achievements, highscores, progress, rating, broken, portable, controller |
show_launch_badges | true | Boolean; shows the "Won't launch" and "Needs attention" readiness badges on the grid from the last Launch Audit. Settings → Appearance. Badges disappear on their own when the library has changed since the audit ran. (v1.16.1+) |
cloud_folder | "" | Absolute, existing path for mounted-folder statistics sync and optional catalog sync |
library_sync_enabled | false | Explicit opt-in for causal catalog synchronization; it does not enable the separate statistics sync automatically |
library_root | "" | Normalized absolute path to the portable library folder; must exist when set. Written by the Move library flow — setting it or path_mode directly outside a move preview/apply is refused. (v3.0.0+) |
path_mode | "absolute" | One of absolute, portable. In portable mode, game paths under library_root are stored as @library/... tokens so the library survives a folder move. Changes only through the Move library flow. (v3.0.0+) |
media_manifest_enabled | true | Boolean; controls whether downloads and captures are recorded in media/manifest.json and whether the integrity report verifies and repairs it. Turning it off skips manifest writes and hashing; the integrity report says the manifest is disabled. Effective since 2.1. |
storefront_auto_import | All off | Object keyed by store (steam, heroic, lutris, gameyfin, gog, ea, ubisoft, or plugin:<id>) whose values are {enabled, platform, include_uninstalled} objects. At most 20 entries; platform is at most 80 characters. Legacy boolean values are still read and are migrated to this shape on the next settings save. |
auto_import_media_types | ["background", "cover", "screenshots"] | Subset of the 23 media types in MEDIA_TYPES_ALL (cover, background, screenshots, clear_logo, fanart, banner, icon, box_back, box_spine, box_3d, title_screen, cart_front, cart_back, disc, advertisement, manual, poster, square, video, video_snap, video_theme, video_trailer, music) |
media_download_limit | 0 (unlimited) | 0 to 10,000 |
region_priority | (default list) | Non-empty ordered list, ranks which regional media to prefer |
video_priority | ["video_snap", "video_theme", "video_trailer", "video_recording"] | Subset of video_snap, video_theme, video_trailer, video_recording, video |
library_music | "" | Path to existing audio file; empty disables Big Box library BGM |
video_bgm_mix | false | Boolean, lower music volume when mixing with video audio |
bigbox_mode | "stage" | One of stage, hybrid, coverflow |
bigbox_start_at_launch | false | Boolean; when true the UI opens straight into Big Box on startup (or unless a ?deeplink=bigbox deeplink overrides it) (v1.14.0+) |
attract_mode_seconds | 90 | Seconds of idle before screensaver/attract mode triggers |
bigbox_startup_video | "" | Empty string (disabled) or path to startup video file |
bigbox_shutdown_commands | [] | At most 25 commands; run when the UI leaves Big Box |
startup_commands | [] | At most 25 commands; run after server binds |
shutdown_commands | [] | At most 25 commands; run on graceful exit |
track_session_history | true | Boolean, when false, sessions still track but history isn't recorded |
backup_on_close | false | Boolean, creates save backups when session ends |
save_backup_limit | 10 | 0 to 500, oldest archives trimmed after each backup |
backup_auto_enabled | false | Boolean; opt-in weekly automatic library backup. 3.0 note: the Rust server's hourly tick currently unlocks time capsules and refreshes tray recents; it does not call auto_backup_due, so scheduled automatic backups do not fire under openbox-server. Use manual or CLI backups until the scheduler is wired. (v1.12.0+) |
backup_auto_keep | 4 | 1 to 52 automatic backup archives retained (v1.12.0+) |
last_auto_backup | "" | Internal timestamp of the last automatic backup; missing or unparsable counts as due — do not edit (v1.12.0+) |
quick_resume_enabled | true | Boolean; enables Quick Resume state capture and restore on state-capable adapters (v1.11.0+) |
session_recap_enabled | true | Boolean; shows the session recap card after a session ends (v1.11.0+) |
moments_autocapture | true | Boolean; automatic Moment capture on qualifying session events (v1.11.0+) |
state_retention | 1 | 1 to 20 Quick Resume states kept per game (v1.11.0+) |
memories_import_enabled | false | Boolean; opt-in import of external media into the Memories gallery (v1.11.0+) |
memories_import_roots | [] | At most 32 absolute, existing directories allowed as Memories import sources (v1.11.0+) |
steamgrid_enabled | true | Boolean; enables the SteamGridDB artwork provider (still requires STEAMGRIDDB_API_KEY) (v1.11.0+) |
scrape_after_import | true | Master toggle for the automatic post-import scrape. Owned by the metadata routes rather than the Settings dialog: read/written through GET/POST /api/v2/metadata/scrape-settings |
scrape_screenscraper_enabled | false | ScreenScraper opt-in for the post-import scrape. Requires all four ScreenScraper values: user, password, developer ID, and developer password |
scrape_igdb_enabled | false | IGDB opt-in for the post-import scrape. Requires IGDB_CLIENT_ID/IGDB_CLIENT_SECRET |
scrape_steamgrid_enabled | false | SteamGridDB opt-in for the post-import scrape. Requires STEAMGRIDDB_API_KEY |
steamgrid_key_configured | (derived) | Read-only projection in public_settings (crates/openbox-http/src/handlers/projection.rs): true when a SteamGridDB API key is configured; not writable via Settings |
obs_replay_enabled | false | Boolean; enables Record That clip capture via the OBS replay buffer (v1.11.0+) |
obs_websocket_url | "" | OBS WebSocket endpoint for replay-buffer capture (v1.11.0+) |
obs_websocket_timeout | 5.0 | 0.1 to 30 seconds for OBS WebSocket calls (v1.11.0+) |
obs_websocket_password | "" | OBS WebSocket password; empty leaves the stored value unchanged (v1.11.0+) |
museum_kiosk_enabled | false | Boolean; Museum/kiosk mode with reduced interaction (v1.11.0+) |
health_rescan | "weekly" | Library health rescan cadence: daily, weekly, on_startup, or off. on_startup runs once at boot when no game session is active; off disables the scheduled tick. 3.0 note: the Rust server does not currently call rescan_due, so only the manual scan runs under openbox-server. (v1.14.0+) |
museum_kiosk_pin_hash | "" | Salted PIN hash for the kiosk convenience boundary — not API authentication (v1.11.0+) |
mood_match_enabled | false | Boolean; enables adaptive cover theming (Mood Match) from the selected artwork. (v1.9.0+) |
mood_match_bigbox | false | Boolean; extends Mood Match to the Big Box background and cover ring. Only effective while mood_match_enabled is true. (v1.9.0+) |
household_stats_sharing | false | Boolean; opt-in sharing of play statistics with Household members (v1.11.0+) |
party_queue | [] | Game Night queue of up to 50 unique game ids (v1.9.0+) |
party_players | 2 | 2 to 8 Game Night players (v1.9.0+) |
party_index | 0 | Current position in the Game Night queue (v1.9.0+) |
tracking_mode | "default" | One of default, process, original_process, folder, process_name |
tracking_delay | 0 | 0 to 600 seconds before tracking starts after spawn |
tracking_frequency | 2.0 | 0.5 to 60 seconds between poll checks |
apply_perf | "auto" | One of off, auto, always, whether TDP limits apply |
auto_close_store_clients | false | Boolean, close Steam/Heroic/Lutris clients after a session ends |
obs_auto_attach | true | Boolean, auto-attaches latest OBS recording to game |
obs_recording_path | "" | Absolute, existing path override; empty uses discovery |
dynamic_play_button | true | Boolean, shows animated PLAY state |
custom_field_defs | [] | Up to 20 fields; each 50 options max |
platform_categories | Built-in mapping | Platform-to-category overrides (Nintendo, Sony, Microsoft, Computer, Arcade, Adventure, Other) |
list_columns | Defaults | Capped at 12 columns per platform or global view |
library_view | "grid" | Current persistent view preference |
hidden_sidebar_sections | [] | Known, unique section ids from sidebar_sections; at most 20 entries |
tray_enabled | false | Boolean, shows system tray icon |
minimize_to_tray | false | Boolean, minimizes to tray instead of closing |
show_playlist_actions | true | Boolean, show add/remove playlist buttons |
gameyfin_url | "" | Prepends http:// when no scheme is given. Not checked for reachability at save time. |
gameyfin_username | "" | Stored as plain text alongside url and password |
gameyfin_password | "" | Empty value leaves the stored password unchanged. Stored in library.json, which is written with mode 0o600. GET /api/v2/settings returns only gameyfin_password_set. |
gameyfin_install_dir | "" | Absolute directory, created if missing (parent folders included). Gameyfin refuses install paths that contain symlinks. Empty by default. |
gameyfin_provider | "" | Provider label; falls back to first available |
ludusavi_backup_path | "" | Optional path for Ludusavi JSON output; created if missing |
cover_grouping | "shape" | String; shape used to group covers in the library |
image_group_by_platform | {} | Object; per-platform image group overrides |
image_group_by_playlist | {} | Object; per-playlist image group overrides |
sidebar_sections | ["search", "view", "filters", "platforms", "playlists", "explorer"] | Ordered list of at most 20 section ids, each at most 40 characters. Current ids: search, view, filters, platforms, playlists, explorer; ids from older builds are preserved so an upgrade does not erase the order. |
platform_documents | {} | Object; per-platform manual/document lists |
filter_presets | [] | List of objects; named filter rules, each needs at least one rule |
import_exclusions | [] | List of objects with source (steam, heroic, lutris, gameyfin, gog, ea, ubisoft) and external_id |
emulator_scan_configs | [] | List of objects; per-emulator scan configuration |
tracking_process_name | "" | String; process name used when tracking_mode is process_name |
webhook_attempts | 3 | 1 to 5 delivery attempts per webhook, including the first |
webhook_timeout | 5 | 1 to 15 seconds before delivery times out |
webhooks | [] | At most 32 configs; each needs a URL and at least one event |
theme | "" | String; global theme name, empty uses the stock theme |
theme_by_platform | {} | Object; platform to theme name mappings |
bigbox_quick | (not stored) | Not written to settings. Big Box quick actions are the filter_presets entries flagged bigbox_quick; at most 8 are shown. |
controller_prompt_pack | "xbox" | String, 20 characters max. Set when a controller media pack is applied (controller-xbox or controller-playstation); not otherwise validated. |
controller_prompt_hint | "" | Text for the controller button hint in Big Box, 200 characters max. Empty uses the built-in hint. Applying a controller media pack sets it to that pack's mapping. A boolean true is stored as the default hint text, and false as empty. |
active_media_packs | [] | List of strings; media pack ids, appended when a pack is applied |
last_cloud_sync | "" | Internal, auto-managed timestamp; do not edit |
last_update_check | "" | Internal, auto-managed timestamp; do not edit |
gameyfin_password_set | false | Read-only in GET /api/v2/settings; true when a Gameyfin password is stored |
gamescope_guest | false | Read-only; derived from the Gamescope environment and --game-mode |
Display, input, and integration settings
The Settings dialog also persists the following keys. Every key in this table except currency shipped in 1.18.0 (currency shipped in 1.17.0). They use the same validation path as the table above; a value that fails validation aborts the whole save, and a value that is merely out of range may be clamped or truncated instead.
| Setting | Default | Validation |
|---|---|---|
auto_import_excluded_platforms | [] | Up to 100 platform names, each at most 80 characters; matching is case-insensitive. Storefront auto-import skips games on these platforms. |
battery_indicator | true | Boolean; shows the battery percentage in the Big Box status area when a battery is present (Linux sysfs, pmset on macOS, or GetSystemPowerStatus on Windows). |
bigbox_back_hold_seconds | 0.8 | 0 to 2 seconds; how long Back must be held in Big Box before it acts. |
bigbox_hidden_categories | [] | Up to 500 category names, each at most 200 characters; hidden from Big Box category browsing. |
bigbox_hidden_platforms | [] | Up to 500 platform names, each at most 200 characters; hidden from Big Box platform browsing. |
bigbox_hidden_playlists | [] | Up to 500 playlist names, each at most 200 characters; hidden from Big Box playlist browsing. |
bigbox_sounds_enabled | true | Boolean; plays Big Box navigation and confirmation sounds. |
bigbox_startup_video_loop | false | Boolean; loops the startup video instead of playing it once. |
bigbox_video_backdrop | false | Boolean; uses the selected game video as a Big Box backdrop. |
bigbox_video_controls | true | Boolean; shows playback controls over Big Box video. |
bigbox_video_volume | 0.8 | 0.0 to 1.0. |
bigbox_wheel_speed | 1.0 | 0.25 to 3.0; multiplies the cover-wheel scroll rate. |
controller_types | Built-in 10-entry list | At most 40 objects with unique lowercase id (32 characters), name (60 characters), and a known kind: gamepad, arcade_stick, racing_wheel, light_gun, paddle, trackball, spinner, keyboard, mouse, or vr. An empty list restores the built-in set. |
cover_model | "box" | One of box, jewel, long_jewel, double_jewel, cassette, or none. |
cover_model_by_platform | {} | At most 200 platform-to-model entries; each value must be one of the cover_model choices. |
currency | "USD" | Three-letter uppercase currency code (ISO-4217 shape). Used as the default for new price-paid values; no exchange-rate conversion is performed. |
emulator_platform_settings | {} | At most 500 platform entries. Each entry accepts adapter_id (120 characters), a validated retroarch_core name, and up to 2,000 characters of extra_args. |
emulator_update_checks | [] | Up to 100 emulator app ids (100 characters each) whose update check is skipped. |
font_family | "system" | One of system, serif, mono, or humanist. |
integration_tokens | {} | Provider-to-token object for igdb, screenscraper, steamgriddb, gameyfin, and retroachievements; each token is at most 4,096 characters. The public settings projection carries only a boolean per provider, and GET /api/v2/integration-tokens returns masked values. |
keyboard_map | {} | Action-to-key object. Actions are play, back, favorite, random, page_left, page_right, pause, menu, search, settings, reader_prev, and reader_next; key specs are validated and no two actions may share a binding. |
last_health_rescan | "" | Internal ISO-8601 timestamp of the last scheduled library health scan; do not edit. |
library_journal_enabled | true | Read-only. The journal records local catalog events for Time Machine even when cloud sync is off; an explicit false already present in library.json disables it. The Settings save path does not write this key. |
media_download_limit_per_group | 0 (unlimited) | 0 to 100; caps queued media downloads per platform-and-kind group. media_download_limit still caps the whole queue. |
metadata_provider_priority | [] (built-in order) | Up to 20 known provider ids or plugin:<id> values. Empty uses launchbox, screenscraper, igdb, steamgriddb, then enabled plugin providers; unknown ids are dropped. |
model_back_by_platform | {} | At most 200 platform-to-style entries; each value is straight or angled. |
model_case_by_platform | {} | At most 200 platform-to-case entries; each value is clear or solid. |
model_rotation_lock | "free" | One of free, horizontal, or vertical. |
model_rotation_lock_by_platform | {} | At most 200 platform-to-lock entries; each value is free, horizontal, or vertical. |
mouse_wheel_nav | true | Boolean; allows the mouse wheel to move through the library and Big Box. |
platform_videos | {} | At most 200 platform-to-path entries; each path must be absolute and point to an existing file. The platform-video route additionally accepts only .mp4, .webm, .ogv, .ogg, or .mkv. |
plugin_metadata_priority | false | Boolean; places enabled plugin metadata providers ahead of built-in providers in the effective priority order. |
pointer_nav_enabled | true | Boolean; enables pointer and touch navigation. |
progress_values | Unplayed, Playing, Paused, Beaten, Completed, Mastered, Abandoned | A list of known progress labels, de-duplicated in the order given. It controls the progress choices and which automatic progress changes are allowed. |
ra_hardcore | false | Boolean; requests hardcore mode when RetroAchievements credentials are injected. |
reader_spread | "single" | One of single or spread; the document reader page layout. |
reader_theme | "light" | One of light or dark; the document reader colour scheme. |
retroachievements_enabled | false (effective) | Read-only effective flag read by Play Insights; when true and a RetroAchievements cache exists, mastery totals include it. The current Settings save path does not write this key. |
save_management_enabled | true | Boolean; when false, save backup, restore, and manifest routes refuse writes and report the feature as disabled. |
save_vault_enabled | true | Boolean; enables Save Vault. session_close and auto snapshots require it; a manual snapshot still works when the vault is enabled. (3.0) |
save_vault_keep | 5 | 1 to 50 snapshots kept per game; older snapshots are pruned. pre-restore safety snapshots are exempt. (3.0) |
save_vault_on_close | false | Boolean; takes a session_close Save Vault snapshot when a game session ends. (3.0) |
save_vault_auto_days | 0 | 0 to 365 days between automatic auto snapshots; 0 disables the schedule. 3.0 note: the Rust server does not currently call auto_vault_due; use manual or on-close snapshots until the scheduler is wired. (3.0) |
deals_enabled | false | Boolean; opt-in Deal Radar. All requests and redirects are restricted to https://store.steampowered.com. (3.0) |
deals_poll_hours | 168 | 24 to 720 hours between Deal Radar polls. 3.0 note: the Rust server does not currently call deals_due; use POST /api/v2/deals/refresh for an immediate poll. (3.0) |
deals_min_drop_pct | 10 | 1 to 90 percent minimum drop for a Deal Radar alert. (3.0) |
deals_store_cc | "us" | Two-letter Steam store country code used for price queries; empty or invalid values fall back to us. (3.0) |
spinner_sensitivity | 6 | 1 to 20; spinner input sensitivity in Big Box. |
One naming detail worth knowing:
attract_mode_secondsis the screensaver delay the Big Box screensaver actually reads; it falls back toscreensaver_secondswhen unset, and the Settings dialog keeps both fields with the same fallback.
One shape detail worth knowing:
storefront_auto_importis stored per source as{enabled, platform, include_uninstalled}. The legacy boolean shape (true/falseper store) is still read, and each legacy boolean is migrated to the object shape on the next settings save — even a partial one, so every reader sees a single shape.
Partial saves merge with existing settings: keys you omit are preserved, and concurrent partial saves of different keys do not lose updates. An empty gameyfin_password or obs_websocket_password in a save leaves the stored value 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).envbootstrap (performed once per process)startup_commands(run after the server binds, viarun_configured_commands)- Profile merging from emulator definition packs (
merge_profiles_from_definitions) at startup
shutdown_commands run on graceful exit. Both command lists are split with split_command (shlex rules on Linux and macOS) and started in 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.envfile is plaintext. - Restart OpenBoxGL after changing values consumed at process startup.
The authoritative sources are .env.example, crates/openbox-io/src/env_config.rs, crates/openbox-http/src/handlers/settings.rs, crates/openbox-core/src/settings.rs, and the Settings dialog. The Python env_config.py, handlers/settings.py, and settings_schema.py remain as the OPENBOX_BACKEND=python fallback.