Environment Variables

homescreen-hero uses environment variables to keep sensitive values (API keys, tokens, passwords) out of config files. Environment variables always override values in config.yaml.

Setup

Create a .env file in the project root (next to docker-compose.yml):

cp .env.example .env

Docker Compose and the backend both automatically load this file.

Required

These are needed for homescreen-hero to function:

Variable	Description	Example
HSH_PLEX_URL	Your Plex server URL	http://192.168.1.100:32400
HSH_PLEX_TOKEN	Your Plex authentication token	abc123xyz

Finding Your Plex Token

1. Sign in to Plex Web App
2. Open any media item
3. Click the three dots menu → "Get Info"
4. Click "View XML"
5. Look for X-Plex-Token in the URL

Or see the official Plex guide.

Authentication

Required when authentication is enabled in settings (auth.enabled = true):

Variable	Description
HSH_AUTH_PASSWORD	Admin password (plaintext or bcrypt hash)
HSH_AUTH_SECRET_KEY	Secret key for JWT token signing (use a random string)

Third-Party Integrations

These are only required if the corresponding integration is enabled:

Trakt

Variable	Description
HSH_TRAKT_CLIENT_ID	Trakt OAuth application client ID

Create an API application at trakt.tv/oauth/applications to get your client ID.

MDBList

Variable	Description
HSH_MDBLIST_API_KEY	MDBList API key

Get your API key from mdblist.com/preferences.

Tautulli

Variable	Description	Default
HSH_TAUTULLI_API_KEY	Tautulli API key	-
HSH_TAUTULLI_BASE_URL	Tautulli server URL	http://localhost:8181

Find your API key in Tautulli under Settings → Web Interface.

Seerr

Variable	Description	Default
HSH_SEERR_API_KEY	Seerr / Jellyseerr / Overseerr API key	-
HSH_SEERR_BASE_URL	Seerr server URL	http://localhost:5055

Application Paths

These control where homescreen-hero stores its data. You typically only need to change these in Docker:

Variable	Description	Default
HOMESCREEN_HERO_CONFIG	Path to config.yaml	config.yaml
HOMESCREEN_HERO_DB	SQLAlchemy database URL	sqlite:///homescreen_hero.sqlite
HOMESCREEN_HERO_LOG_DIR	Log file directory	logs

In the default Docker setup, these are pre-configured to use /data:

HOMESCREEN_HERO_CONFIG: /data/config.yaml
HOMESCREEN_HERO_DB: sqlite:////data/homescreen_hero.sqlite
HOMESCREEN_HERO_LOG_DIR: /data/logs

Override Priority

Environment variables always take priority over config.yaml values. This means you can:

1. Use the Setup Wizard to configure most settings
2. Override sensitive values with environment variables
3. Keep your .env file out of version control (it's in .gitignore)

tip

Set up your .env file before running the Setup Wizard. The wizard will detect existing environment variables and skip those fields, so your secrets never get written to config.yaml.