Environment Variables

Everything RomM does that's not in config.yml is driven by env vars. Set them on the romm service in your compose file, as Unraid/Synology/TrueNAS container env vars, or on your Kubernetes deployment.

This page is the authoritative lookup! The table is generated directly from rommapp/romm's env.template at the SHA pinned in scripts/sources.toml. When RomM adds an env var, the next docs bump re-runs the generator and this page updates.

Setting env vars

Docker Compose

services:
    romm:
        environment:
            - ROMM_AUTH_SECRET_KEY=abcd1234...
            - DB_PASSWD=secure-password
            # ...

Or from a .env file next to your compose:

services:
    romm:
        env_file:
            - .env

Secrets

Don't embed ROMM_AUTH_SECRET_KEY, DB passwords, or provider API keys directly in a committed compose file. Use:

A .env that's .gitignored
Docker secrets (ROMM_AUTH_SECRET_KEY_FILE reads from a mounted file)
Your orchestrator's secret store (K8s Secrets, HashiCorp Vault, AWS Secrets Manager)

Essential variables

You'll always set these:

Variable	Purpose
`ROMM_AUTH_SECRET_KEY`	JWT signing key generated with `openssl rand -hex 32`
`DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASSWD`	Database connection
`ROMM_DB_DRIVER`	One of `mariadb` (default), `mysql`, or `postgresql` (see Databases)

For metadata providers (IGDB, ScreenScraper, etc.) see Metadata Providers, and for OIDC, see OIDC Setup.

Full reference

Core Application

Variable	Default	Description
`ROMM_BASE_PATH`	`/romm`	Base folder path for library, resources and assets
`ROMM_TMP_PATH`		Custom temporary directory path
`ROMM_BASE_URL`	`http://0.0.0.0`	Public URL of this instance
`ROMM_PORT`	`8080`	Port on which the application listens
`KIOSK_MODE`	`false`	Let visitors browse without logging in (read-only)

Database

Variable	Default	Required	Description
`ROMM_DB_DRIVER`	`mariadb`		Database driver to use (mariadb, mysql, postgresql)
`DB_HOST`		`✓`	Host name of the database instance
`DB_PORT`	`3306`		Port number of the database instance
`DB_NAME`	`romm`		Database name (should match MYSQL_DATABASE in MariaDB)
`DB_USER`		`✓`	Database username (should match MARIADB_USER in MariaDB)
`DB_PASSWD`		`✓`	Database password (should match MARIADB_PASSWORD in MariaDB)
`DB_ROOT_PASSWD`			Database root user password (only used by the bundled MariaDB container)
`DB_QUERY_JSON`			Extra query parameters for the database connection, as JSON
`DB_POOL_RECYCLE_SECONDS`	`300`		Retire a pooled connection after this long, before the server drops it for being idle (-1 to never recycle)

Redis/Valkey

Variable	Default	Description
`REDIS_HOST`	`127.0.0.1`	Host name of the Redis/Valkey instance
`REDIS_PORT`	`6379`	Port number of the Redis/Valkey instance
`REDIS_USERNAME`		Username for the Redis/Valkey instance
`REDIS_PASSWORD`		Password for the Redis/Valkey instance
`REDIS_DB`	`0`	Database number for the Redis/Valkey instance
`REDIS_SSL`	`false`	Enable SSL (rediss://) for the Redis/Valkey connection
`REDIS_SAVE_POLICY`	`3600 1`	Snapshot policy of the internal Valkey, as " " pairs (empty to never snapshot)

Authentication

Variable	Default	Required	Description
`ROMM_AUTH_SECRET_KEY`		`✓`	App secret, generate with `openssl rand -hex 32`
`OAUTH_ACCESS_TOKEN_EXPIRE_SECONDS`	`1800`		Access token lifetime in seconds
`OAUTH_REFRESH_TOKEN_EXPIRE_SECONDS`	`604800`		Refresh token lifetime in seconds
`SESSION_MAX_AGE_SECONDS`	`1209600`		Maximum age of a session in seconds
`INVITE_TOKEN_EXPIRY_SECONDS`	`600`		Invite token lifetime in seconds
`DISABLE_DOWNLOAD_ENDPOINT_AUTH`	`false`		Disable auth on the download endpoint for WebRcade/Tinfoil
`DISABLE_CSRF_PROTECTION`	`false`		Disable CSRF protection (not recommended)
`DISABLE_USERPASS_LOGIN`	`false`		Disable username/password login when using OIDC
`DISABLE_SETUP_WIZARD`	`false`		Skip the first-boot setup wizard
`DISABLE_LOGS_VIEWER`	`false`		Disable the backend logs viewer
`ROMM_CORS_ALLOWED_ORIGINS`			Comma-separated list of allowed CORS origins (empty allows all)
`ROMM_SESSION_SECURE_COOKIE`	`false`		Mark session and CSRF cookies Secure (enable when served over HTTPS)

OpenID Connect

Variable	Default	Description
`OIDC_ENABLED`	`false`	Enable OpenID Connect authentication
`OIDC_AUTOLOGIN`	`false`	Skip the OIDC button on the login page and auto-redirect
`OIDC_ALLOW_REGISTRATION`	`true`	Allow new accounts to be created automatically on first OIDC login
`OIDC_PROVIDER`		Name of the OIDC provider in use
`OIDC_CLIENT_ID`		Client ID for OIDC authentication
`OIDC_CLIENT_SECRET`		Client secret for OIDC authentication
`OIDC_REDIRECT_URI`		Absolute redirect URI for OIDC authentication
`OIDC_SERVER_APPLICATION_URL`		Absolute URL of the OIDC server application
`OIDC_SERVER_METADATA_URL`		URL to the OIDC provider metadata endpoint
`OIDC_CLAIM_ROLES`		OIDC claim containing user roles
`OIDC_ROLE_VIEWER`		Role value mapping to viewer permissions
`OIDC_ROLE_EDITOR`		Role value mapping to editor permissions
`OIDC_ROLE_ADMIN`		Role value mapping to admin permissions
`OIDC_TLS_CACERTFILE`		Path to file containing trusted CA certificates
`OIDC_USERNAME_ATTRIBUTE`	`preferred_username`	Attribute on OIDC user info used as the username
`OIDC_RP_INITIATED_LOGOUT`	`false`	Enable RP-initiated logout flow
`OIDC_END_SESSION_ENDPOINT`		OIDC end-session endpoint override URL

Metadata Providers

Variable	Default	Description
`IGDB_CLIENT_ID`		Client ID for the IGDB API
`IGDB_CLIENT_SECRET`		Client secret for the IGDB API
`MOBYGAMES_API_KEY`		MobyGames secret API key
`SCREENSCRAPER_USER`		Screenscraper username
`SCREENSCRAPER_PASSWORD`		Screenscraper password
`STEAMGRIDDB_API_KEY`		SteamGridDB secret API key
`RETROACHIEVEMENTS_API_KEY`		RetroAchievements secret API key
`REFRESH_RETROACHIEVEMENTS_CACHE_DAYS`	`30`	RetroAchievements metadata cache refresh interval in days
`PLAYMATCH_API_ENABLED`	`false`	Enable PlayMatch API integration
`LAUNCHBOX_API_ENABLED`	`false`	Enable LaunchBox API integration
`HASHEOUS_API_ENABLED`	`false`	Enable Hasheous API integration
`FLASHPOINT_API_ENABLED`	`false`	Enable Flashpoint API integration
`HLTB_API_ENABLED`	`false`	Enable HowLongToBeat API integration
`DEMOZOO_API_ENABLED`	`false`	Enable Demozoo (filename tags (demozoo-N) / paste ID; no API key)
`POUET_API_ENABLED`	`false`	Enable Pouët (filename tags (pouet-N) / paste ID; no API key)
`CSDB_API_ENABLED`	`false`	Enable CSDb (filename tags (csdb-N) / paste ID / Demozoo CsdbRelease; no API key)
`STEAM_API_ENABLED`	`false`	Enable Steam API integration (PC platforms only)
`TGDB_API_ENABLED`	`false`	Enable TheGamesDB API integration

Physical Games

Variable	Default	Description
`UPC_LOOKUP_ENABLED`	`true`	Look a barcode up by UPC when adding a physical game
`UPC_LOOKUP_API_KEY`		Key for the UPC lookup service, if your plan needs one
`UPC_LOOKUP_URL`	`https://api.upcitemdb.com/prod/trial/lookup`	UPC lookup endpoint

Scans & Tasks

Variable	Default	Description
`SCAN_TIMEOUT`	`14400`	Timeout for background scan/rescan tasks in seconds
`SCAN_WORKERS`	`4`	How many ROMs a scan processes at once
`TASK_TIMEOUT`	`300`	Timeout for other background tasks in seconds
`TASK_RESULT_TTL`	`86400`	How long to keep task results in Valkey in seconds
`SEVEN_ZIP_TIMEOUT`	`60`	Timeout for 7-Zip operations in seconds
`ENABLE_RESCAN_ON_FILESYSTEM_CHANGE`	`false`	Re-scan the library automatically when the filesystem changes
`RESCAN_ON_FILESYSTEM_CHANGE_DELAY`	`5`	Delay in minutes before re-scanning after a filesystem change
`ENABLE_SCHEDULED_RESCAN`	`false`	Enable scheduled library re-scans
`SCHEDULED_RESCAN_CRON`	`0 3 * * *`	Cron expression for scheduled re-scans
`ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB`	`false`	Enable scheduled Switch TitleDB index updates
`SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON`	`0 4 * * *`	Cron expression for scheduled Switch TitleDB updates
`ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA`	`false`	Enable scheduled LaunchBox metadata updates
`SCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRON`	`0 4 * * *`	Cron expression for scheduled LaunchBox metadata updates
`ENABLE_SCHEDULED_CONVERT_IMAGES_TO_WEBP`	`false`	Enable scheduled conversion of images to WebP
`SCHEDULED_CONVERT_IMAGES_TO_WEBP_CRON`	`0 4 * * *`	Cron expression for scheduled WebP conversion
`ENABLE_SCHEDULED_CLEANUP_ORPHANED_RESOURCES`	`false`	Enable scheduled cleanup of orphaned resources (covers, screenshots) left by deleted ROMs
`SCHEDULED_CLEANUP_ORPHANED_RESOURCES_CRON`	`0 5 * * *`	Cron expression for scheduled orphaned resource cleanup
`ENABLE_SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC`	`false`	Enable scheduled RetroAchievements progress sync
`SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC_CRON`	`0 4 * * *`	Cron expression for scheduled RetroAchievements sync
`ENABLE_SCHEDULED_BUILD_RECOMMENDATIONS`	`true`	Enable the scheduled rebuild of the recommendations index
`SCHEDULED_BUILD_RECOMMENDATIONS_CRON`	`30 5 * * *`	Cron expression for the recommendations index rebuild

Sync

Variable	Default	Description
`ENABLE_SYNC_FOLDER_WATCHER`	`false`	Watch the sync folder and trigger scans on change
`SYNC_FOLDER_SCAN_DELAY`	`2`	Delay in minutes before scanning after a sync folder change
`ENABLE_SYNC_PUSH_PULL`	`false`	Enable scheduled sync push/pull
`SYNC_PUSH_PULL_CRON`	`/30 * * *`	Cron expression for scheduled sync push/pull
`SYNC_SSH_KEYS_PATH`		Path to SSH keys for sync remotes (defaults to $ROMM_BASE_PATH/sync/keys)
`SYNC_SSH_KNOWN_HOSTS_PATH`		Path to SSH known_hosts (defaults to $ROMM_BASE_PATH/sync/known_hosts)

Emulation

Variable	Default	Description
`DISABLE_EMULATOR_JS`	`false`	Disable in-browser play via EmulatorJS
`DISABLE_RUFFLE_RS`	`false`	Disable in-browser Flash playback via RuffleRS
`DISABLE_JSDOS`	`false`	Disable in-browser Win3.x and Win9.x playback via js-dos
`DISABLE_PICO8`	`false`	Disable in-browser PICO-8 playback via FAKE-08

Integrations

Variable	Default	Required	Description
`YOUTUBE_BASE_URL`	`https://www.youtube.com`		Base URL for alternate YouTube frontends (Piped, Invidious, etc.)
`TINFOIL_WELCOME_MESSAGE`	`RomM Switch Library`		Welcome message shown in Tinfoil Switch clients

Assets

Variable	Default	Required	Description
`MAX_ASSET_UPLOAD_SIZE_BYTES`	`536870912`		Max size of a save/state/screenshot upload request in bytes (0 disables the limit)
`MAX_AUTOCLEANUP_LIMIT`	`100`		Max number of saves a client can keep per slot when autocleanup is on (minimum 1)

Logging

Variable	Default	Description
`LOGLEVEL`	`INFO`	Application log level
`FORCE_COLOR`	`false`	Force colored log output
`NO_COLOR`	`false`	Disable colored log output

Web Server

Variable	Default	Description
`WEB_SERVER_CONCURRENCY`	`4`	Number of API worker processes, raise for several concurrent users
`WEB_SERVER_TIMEOUT`	`300`	Timeout for web server requests in seconds
`WEB_SERVER_KEEPALIVE`	`2`	Keep-Alive connection wait time in seconds
`WEB_SERVER_MAX_REQUESTS`	`1000`	Maximum requests a worker processes before restarting
`WEB_SERVER_MAX_REQUESTS_JITTER`	`100`	Random jitter added to max requests value
`WEB_SERVER_WORKER_CONNECTIONS`	`1000`	Maximum simultaneous clients per worker process
`WEB_SERVER_GUNICORN_WAIT_SECONDS`	`30`	Seconds to wait for Gunicorn to start before giving up
`IPV4_ONLY`	`false`	Bind only to IPv4

Proxy

Variable	Default	Required	Description
`HTTP_PROXY`			HTTP proxy URL for outbound requests
`HTTPS_PROXY`			HTTPS proxy URL for outbound requests
`NO_PROXY`			Comma-separated list of hosts to bypass the proxy

Observability

Variable	Default	Required	Description
`SENTRY_DSN`			DSN for Sentry error tracking

Development

Variable	Default	Description
`DEV_MODE`	`false`	Enable development mode (debugging, hot-reloading)
`DEV_HOST`	`127.0.0.1`	Host for the development server
`DEV_PORT`	`5000`	Port for the development server
`DEV_HTTPS`	`false`	Enable HTTPS in the development server
`DEV_SQL_ECHO`	`false`	Log all SQL queries in development mode
`POSTGRES_DB`	`authentik`	Postgres database name for the Authentik dev stack
`POSTGRES_USER`	`authentik`	Postgres user for the Authentik dev stack
`POSTGRES_PASSWORD`	`authentik`	Postgres password for the Authentik dev stack
`AUTHENTIK_SECRET_KEY`		Authentik secret key
`AUTHENTIK_BOOTSTRAP_PASSWORD`		Initial Authentik admin bootstrap password

Emulator Streaming

Variable	Default	Description
`STREAMING_BROKER_SECRET`		Shared secret matching streaming containers' BROKER_SECRET, required for broker auth
`STREAMING_SAVE_TIMEOUT`	`45`	Seconds to wait for a broker save-and-exit (raise if a broker has SAVE_WAIT > 45)
`STREAMING_LAUNCH_TIMEOUT`	`600`	Seconds a webstation activate may take, covering pkg/archive extraction before the emulator starts
`STREAMING_STATE_HISTORY_LIMIT`	`50`	Save states kept per ROM, emulator and user; oldest are pruned past this (0 disables)