// 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

SourceWhen it is readPrecedence
Process environmentAt startup and on demand (os.environ)Highest for every variable it defines
Discovered .env filesbootstrap_env at Web UI startup, lazily before some lookupsNever overrides an existing environment value
Persisted settingslibrary.json -> settingsProvider-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:

ProviderOrder
RetroAchievementsretroachievements.json in the data directory, then the environment
EmuMoviesemumovies.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, SteamGridDBEnvironment only
GameyfinSettings only (library.json); no environment variables

.env discovery order

openbox-io 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.
  6. On Windows only, %APPDATA%\openbox-game-launcher and %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

VariableMeaning
OPENBOX_DATA_DIRData 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_BINExplicit 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_BACKENDSet to python to run the legacy web_app.py backend instead of Rust. The default is rust.
OPENBOX_ROOTApplication asset/share root (index.html, static/, locales/, themes/, emulator_defs/, plugin_runner_v2.py).
OPENBOX_PORTBind a specific 127.0.0.1 port instead of an ephemeral one (0, default).
OPENBOX_SAFE_MODEAny 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).
APPIMAGESet 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_FILEExplicit 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_WEBHOOKSSet to 1 to allow plain-HTTP webhook URLs. Required only for trusted local test targets; HTTPS is the default and safer.
OPENBOX_ALLOW_HTTP_GAMEYFINSet to 1 to allow plain-HTTP Gameyfin URLs. HTTPS is the default; loopback (localhost) addresses are always allowed.
OPENBOX_ALLOW_UNSANDBOXED_PLUGINSSet 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_ROOTSColon-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_EXECUTABLEOptional 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_DMABUFSet 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_ACCELERATIONWebKitGTK hardware acceleration policy in the Linux native window (always or on-demand; default is on-demand). Process environment only (not .env).
OPENBOX_SNAPSHOT_DEBOUNCEPython 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_DIRCustom 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_TAGPins a specific GitHub release tag (e.g. v3.0.0) during install.sh execution.
OPENBOX_PYTHONPython 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_APPPython fallback only: path to web_app.py used when OPENBOX_BACKEND=python or no openbox-server binary is found.
OPENBOX_NATIVE_HOSTPath 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_SHARERuntime directory override used by the Windows launchers (openbox.ps1, openbox-native.ps1) to point at the extracted runtime tree.
OPENBOX_BUNDLED_LIB_PATHLD_LIBRARY_PATH value used by the AppImage wrapper for bundled libraries.
OPENBOX_ARCHOverrides uname -m architecture detection in install.sh and build_appimage.sh (x86_64 or aarch64).
OPENBOX_UPDATE_INFORMATIONzsync update-metadata line embedded by build_appimage.sh for the verified updater (packaging-time, not user-facing).
OPENBOX_RELEASE_BASEBase 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_READSet 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 pointWhat it does
openbox.cmdDouble-clickable wrapper
openbox.ps1Runs the ladder: the native WebView2 window first, the browser app window second. --web forces the browser app window.
openbox-native.ps1Runs 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)

VariableUsed byAliases
RETROACHIEVEMENTS_USERNAMERetroAchievements matching and progressRA_USERNAME, OPENBOX_RA_USERNAME
RETROACHIEVEMENTS_API_KEYRetroAchievements web APIRA_API_KEY, RETROACHIEVEMENTS_KEY, OPENBOX_RA_API_KEY
EMUMOVIES_USERNAMEEmuMovies media downloadsOPENBOX_EMUMOVIES_USERNAME
EMUMOVIES_PASSWORDEmuMovies media downloadsOPENBOX_EMUMOVIES_PASSWORD
GITHUB_TOKENGitHub release API rate limit for update checks (GITHUB_TOKEN, GH_TOKEN, OPENBOX_GITHUB_TOKEN all accepted)GH_TOKEN, OPENBOX_GITHUB_TOKEN
IGDB_CLIENT_IDIGDB metadata provider (Twitch developer app),
IGDB_CLIENT_SECRETIGDB metadata provider (Twitch developer app),
STEAMGRIDDB_API_KEYSteamGridDB artwork provider: search, apply, and bulk matchingOPENBOX_STEAMGRIDDB_API_KEY
SCREENSCRAPER_USERScreenScraper per-ROM-hash scraping (required for that provider)OPENBOX_SCREENSCRAPER_USER
SCREENSCRAPER_PASSWORDScreenScraper per-ROM-hash scraping (required for that provider)OPENBOX_SCREENSCRAPER_PASSWORD
SCREENSCRAPER_DEV_IDScreenScraper developer credentials (required for that provider; the API refuses lookups without them)OPENBOX_SCREENSCRAPER_DEV_ID
SCREENSCRAPER_DEV_PASSWORDScreenScraper developer credentials (required for that provider)OPENBOX_SCREENSCRAPER_DEV_PASSWORD
STEAM_API_KEYSteam Web API key for achievement and playtime import. Process environment only (not .env).
STEAM_IDSteam 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:

SettingDefaultValidation
watch_folders[]List of at most 50 absolute, existing directories; duplicates removed
screensaver_seconds900 (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_enabledfalseBoolean; 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_insightstrueBoolean; 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_enabledfalseBoolean; enables/disables automatic progress changes
progress_automation_play_minutes300 to 100,000, minutes before marking Playing
progress_automation_idle_days300 to 3,650, days before marking Paused
progress_on_first_play"Playing"Must be a known progress status
welcome_completedfalseBoolean, suppresses opening the Library Setup Center on empty library launch
backlog_progress_suggesttrueBoolean; 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_visibilityfavorite, installed, saves, documents, progress, storefront, achievements, ratingSubset of favorite, installed, missing_media, saves, documents, versions, storefront, achievements, highscores, progress, rating, broken, portable, controller
show_launch_badgestrueBoolean; 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_enabledfalseExplicit 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_enabledtrueBoolean; 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_importAll offObject 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_limit0 (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_mixfalseBoolean, lower music volume when mixing with video audio
bigbox_mode"stage"One of stage, hybrid, coverflow
bigbox_start_at_launchfalseBoolean; when true the UI opens straight into Big Box on startup (or unless a ?deeplink=bigbox deeplink overrides it) (v1.14.0+)
attract_mode_seconds90Seconds 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_historytrueBoolean, when false, sessions still track but history isn't recorded
backup_on_closefalseBoolean, creates save backups when session ends
save_backup_limit100 to 500, oldest archives trimmed after each backup
backup_auto_enabledfalseBoolean; 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_keep41 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_enabledtrueBoolean; enables Quick Resume state capture and restore on state-capable adapters (v1.11.0+)
session_recap_enabledtrueBoolean; shows the session recap card after a session ends (v1.11.0+)
moments_autocapturetrueBoolean; automatic Moment capture on qualifying session events (v1.11.0+)
state_retention11 to 20 Quick Resume states kept per game (v1.11.0+)
memories_import_enabledfalseBoolean; 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_enabledtrueBoolean; enables the SteamGridDB artwork provider (still requires STEAMGRIDDB_API_KEY) (v1.11.0+)
scrape_after_importtrueMaster 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_enabledfalseScreenScraper opt-in for the post-import scrape. Requires all four ScreenScraper values: user, password, developer ID, and developer password
scrape_igdb_enabledfalseIGDB opt-in for the post-import scrape. Requires IGDB_CLIENT_ID/IGDB_CLIENT_SECRET
scrape_steamgrid_enabledfalseSteamGridDB 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_enabledfalseBoolean; 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_timeout5.00.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_enabledfalseBoolean; 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_enabledfalseBoolean; enables adaptive cover theming (Mood Match) from the selected artwork. (v1.9.0+)
mood_match_bigboxfalseBoolean; extends Mood Match to the Big Box background and cover ring. Only effective while mood_match_enabled is true. (v1.9.0+)
household_stats_sharingfalseBoolean; 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_players22 to 8 Game Night players (v1.9.0+)
party_index0Current position in the Game Night queue (v1.9.0+)
tracking_mode"default"One of default, process, original_process, folder, process_name
tracking_delay00 to 600 seconds before tracking starts after spawn
tracking_frequency2.00.5 to 60 seconds between poll checks
apply_perf"auto"One of off, auto, always, whether TDP limits apply
auto_close_store_clientsfalseBoolean, close Steam/Heroic/Lutris clients after a session ends
obs_auto_attachtrueBoolean, auto-attaches latest OBS recording to game
obs_recording_path""Absolute, existing path override; empty uses discovery
dynamic_play_buttontrueBoolean, shows animated PLAY state
custom_field_defs[]Up to 20 fields; each 50 options max
platform_categoriesBuilt-in mappingPlatform-to-category overrides (Nintendo, Sony, Microsoft, Computer, Arcade, Adventure, Other)
list_columnsDefaultsCapped 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_enabledfalseBoolean, shows system tray icon
minimize_to_trayfalseBoolean, minimizes to tray instead of closing
show_playlist_actionstrueBoolean, 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_attempts31 to 5 delivery attempts per webhook, including the first
webhook_timeout51 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_setfalseRead-only in GET /api/v2/settings; true when a Gameyfin password is stored
gamescope_guestfalseRead-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.

SettingDefaultValidation
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_indicatortrueBoolean; 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_seconds0.80 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_enabledtrueBoolean; plays Big Box navigation and confirmation sounds.
bigbox_startup_video_loopfalseBoolean; loops the startup video instead of playing it once.
bigbox_video_backdropfalseBoolean; uses the selected game video as a Big Box backdrop.
bigbox_video_controlstrueBoolean; shows playback controls over Big Box video.
bigbox_video_volume0.80.0 to 1.0.
bigbox_wheel_speed1.00.25 to 3.0; multiplies the cover-wheel scroll rate.
controller_typesBuilt-in 10-entry listAt 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_enabledtrueRead-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_group0 (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_navtrueBoolean; 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_priorityfalseBoolean; places enabled plugin metadata providers ahead of built-in providers in the effective priority order.
pointer_nav_enabledtrueBoolean; enables pointer and touch navigation.
progress_valuesUnplayed, Playing, Paused, Beaten, Completed, Mastered, AbandonedA list of known progress labels, de-duplicated in the order given. It controls the progress choices and which automatic progress changes are allowed.
ra_hardcorefalseBoolean; 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_enabledfalse (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_enabledtrueBoolean; when false, save backup, restore, and manifest routes refuse writes and report the feature as disabled.
save_vault_enabledtrueBoolean; enables Save Vault. session_close and auto snapshots require it; a manual snapshot still works when the vault is enabled. (3.0)
save_vault_keep51 to 50 snapshots kept per game; older snapshots are pruned. pre-restore safety snapshots are exempt. (3.0)
save_vault_on_closefalseBoolean; takes a session_close Save Vault snapshot when a game session ends. (3.0)
save_vault_auto_days00 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_enabledfalseBoolean; opt-in Deal Radar. All requests and redirects are restricted to https://store.steampowered.com. (3.0)
deals_poll_hours16824 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_pct101 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_sensitivity61 to 20; spinner input sensitivity in Big Box.

One naming detail worth knowing:

  • 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.

One shape detail worth knowing:

  • storefront_auto_import is stored per source as {enabled, platform, include_uninstalled}. The legacy boolean shape (true / false per 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)
  • .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 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 .env file 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.