Configuration

homescreen-hero stores its settings in config.yaml. Most settings can be managed through the dashboard UI, but you can also edit this file directly. You can also export, import, and revert your config from the Settings page.

Security Tip

Sensitive values like API keys and passwords should be set using environment variables instead of putting them directly in config.yaml.

Example Config

plex:
  base_url: "YOUR_PLEX_SERVER_URL"  # e.g., "http://192.168.1.100:32400"
  # token: "YOUR_PLEX_TOKEN"  # RECOMMENDED: Use HSH_PLEX_TOKEN environment variable instead
  libraries: # List of Plex libraries to use
    - name: Movies
      enabled: true
    - name: TV Shows
      enabled: false

auth:
  enabled: true
  username: "admin"
  # password: ""  # RECOMMENDED: Use HSH_AUTH_PASSWORD environment variable instead
  # secret_key: ""  # RECOMMENDED: Use HSH_AUTH_SECRET_KEY environment variable instead
  token_expire_days: 30

rotation:
  enabled: true
  interval_hours: 12
  max_collections: 5
  group_order: display_order # display_order, weighted, or random
  allow_repeats: false
  sync_all_on_rotation: true # Default: true

trakt:
  enabled: false
  # client_id: "YOUR_TRAKT_CLIENT_ID"  # RECOMMENDED: Use HSH_TRAKT_CLIENT_ID environment variable instead
  base_url: https://api.trakt.tv
  sources:
  - name: "TRAKT_COLLECTION_NAME"  # This is the name that will show up in Plex
    url: "LINK_TO_TRAKT_COLLECTION_OR_LIST"  # e.g., https://trakt.tv/users/username/collections/movies
    plex_library: "YOUR_PLEX_LIBRARY_NAME" # e.g., "Movies"

letterboxd:
  sources:
  - name: "LETTERBOXD_LIST_NAME"  # This is the name that will show up in Plex
    url: "LINK_TO_LETTERBOXD_LIST"  # e.g., https://letterboxd.com/username/list/listname/
    plex_library: "YOUR_PLEX_LIBRARY_NAME" # e.g., "Movies"

mdblist:
  enabled: false
  # api_key: "YOUR_MDBLIST_API_KEY"  # RECOMMENDED: Use HSH_MDBLIST_API_KEY environment variable instead
  base_url: https://api.mdblist.com
  sources:
  - name: "MDBLIST_LIST_NAME"  # This is the name that will show up in Plex
    url: "LINK_TO_MDBLIST_LIST"  # e.g., https://mdblist.com/lists/username/listname
    plex_library: "YOUR_PLEX_LIBRARY_NAME" # e.g., "Movies"

tautulli:
  enabled: false
  # api_key: "YOUR_TAUTULLI_API_KEY"  # RECOMMENDED: Use HSH_TAUTULLI_API_KEY environment variable instead
  # Get your API key from: Tautulli Settings → Web Interface → API → API Key
  base_url: "http://localhost:8181"  # Your Tautulli instance URL
  collect_on_rotation: true  # Automatically collect analytics after each rotation
  collect_interval_hours: 24  # How often to collect analytics snapshots (in hours)

seerr:
  enabled: false
  # api_key: "YOUR_SEERR_API_KEY"  # RECOMMENDED: Use HSH_SEERR_API_KEY environment variable instead
  # Get your API key from: Seerr Settings → General → API Key
  base_url: "http://localhost:5055"  # Your Seerr instance URL

tmdb:
  enabled: false
  # api_key: "YOUR_TMDB_API_KEY"  # RECOMMENDED: Use HSH_TMDB_API_KEY environment variable instead
  sources:
  - name: "TMDB_COLLECTION_NAME"
    url: "https://www.themoviedb.org/list/123456"
    plex_library: "Movies"

anilist:
  sources:
  - name: "ANILIST_COLLECTION_NAME"  # This is the name that will show up in Plex
    url: "https://anilist.co/user/USERNAME/animelist/Completed"  # User list URL
    plex_library: "Anime"
  - name: "AniList Top 100"
    url: "anilist://browse/top-100"  # Browse list URL
    plex_library: "Anime"
    max_items: 100  # 10-500, only applies to browse lists

mal:
  enabled: false
  # client_id: "YOUR_MAL_CLIENT_ID"  # RECOMMENDED: Use HSH_MAL_CLIENT_ID environment variable instead
  sources:
  - name: "MAL_COLLECTION_NAME"
    url: "https://myanimelist.net/animelist/USERNAME"
    plex_library: "Anime"

display:
  group_display_mode: grouped  # "grouped" (clustered by group) or "merged" (round-robin)

logging:
  level: INFO

groups:
- name: ExampleGroup
  enabled: true
  min_picks: 1
  max_picks: 1
  weight: 1
  min_gap_rotations: 0
  display_order: 0  # Controls position on homescreen (lower = first)
  visibility_home: true        # Show collections on server owner's Home page
  visibility_shared: false     # Show collections on shared users' Home pages
  visibility_recommended: false  # Show collections on Library Recommended section
  target_users:               # Optional: restrict to specific Plex users (omit for everyone)
    - username1
    - username2
  collections:
  - Example Collection 1
  - Example Collection 2

- name: SmartGroupExample
  enabled: true
  smart: true                  # Uses filter rules instead of manual collection list
  rules:
    - field: source
      operator: is
      values: [trakt]
    - field: item_count
      operator: gte
      values: [10]
  min_picks: 1
  max_picks: 2

Section Reference

plex

Field	Type	Default	Description
`base_url`	string	-	Plex server URL
`token`	string	null	Plex API token (prefer env var)
`libraries`	list	-	Libraries to manage
`libraries[].name`	string	-	Library name in Plex
`libraries[].enabled`	bool	true	Whether this library is active

rotation

Field	Type	Default	Description
`enabled`	bool	true	Enable automatic rotation
`interval_hours`	int	12	Hours between rotations (min: 1)
`max_collections`	int	5	Max collections on homescreen at once (min: 1)
`group_order`	string	display_order	How groups are ordered for processing: `display_order`, `weighted`, or `random`
`allow_repeats`	bool	false	Allow same collection in consecutive rotations
`sync_all_on_rotation`	bool	true	Sync all third-party lists when rotating
`blacklisted_collections`	list	[]	Collections to never select during rotation
`auto_rotate`	object	-	Settings for auto-rotate mode
`per_library_limits`	object		Maximum collections per library during rotation. Keys are library names, values are max counts

Group Order

Controls how groups are processed during rotation:

display_order - Groups processed in their configured display order
weighted - Groups sorted by weight (higher = first), so higher-priority groups pick before lower ones
random - Groups processed in random order

groups

Groups organize your Plex collections for rotation.

Field	Type	Default	Description
`name`	string	-	Group name
`enabled`	bool	true	Whether group is active
`min_picks`	int	0	Minimum collections to pick per rotation
`max_picks`	int	1	Maximum collections to pick per rotation
`weight`	int	1	Priority for `weighted` strategy (higher = more likely)
`min_gap_rotations`	int	0	Rotations before reusing a collection from this group
`display_order`	int	0	Order groups appear in UI/Plex homescreen
`visibility_home`	bool	true	Show on admin Home page
`visibility_shared`	bool	false	Show on shared users' Home pages
`visibility_recommended`	bool	false	Show in Library Recommended section
`date_range`	object	null	Restrict group to a yearly date window
`date_range.start`	string	-	Start date in `MM-DD` format
`date_range.end`	string	-	End date in `MM-DD` format
`smart`	bool	false	Use filter rules instead of a manual collection list
`rules`	list	[]	Smart group filter rules (only when `smart: true`). See Smart Groups
`target_users`	list	null	Plex usernames who should see this group's collections. Omit for everyone. See Per-User Targeting
`collection_selection`	string	random	How collections are picked: `random` or `lru`
`collection_order`	string	null	Display order on homescreen: `random` or `alpha`
`collection_sort`	string	null	Sort order for items within collections: `release` or `alpha`
`collections`	list	-	Plex collection names in this group (ignored when `smart: true`)

auth

Field	Type	Default	Description
`enabled`	bool	false	Require login to access the dashboard
`method`	string	password	Auth method: `password`, `plex`, or `both`
`username`	string	admin	Login username (password method only)
`password`	string	null	Password - plaintext or bcrypt hash (prefer env var)
`secret_key`	string	null	JWT signing secret (prefer env var)
`token_expire_days`	int	30	Days before login expires
`auto_approve_users`	bool	true	Auto-approve new Plex users (Plex auth only)

trakt

Field	Type	Default	Description
`enabled`	bool	false	Enable Trakt integration
`client_id`	string	null	Trakt API client ID (prefer env var)
`base_url`	string	`https://api.trakt.tv`	Trakt API base URL
`sources`	list	[]	Trakt list sources to sync
`sources[].name`	string	-	Display name (becomes the Plex collection name)
`sources[].url`	string	-	Full Trakt list URL
`sources[].plex_library`	string	-	Target Plex library to sync into

mdblist

Field	Type	Default	Description
`enabled`	bool	false	Enable MDBList integration
`api_key`	string	null	MDBList API key (prefer env var)
`base_url`	string	`https://api.mdblist.com`	MDBList API base URL
`sources`	list	[]	MDBList sources to sync
`sources[].name`	string	-	Display name (becomes the Plex collection name)
`sources[].url`	string	-	Full MDBList list URL
`sources[].plex_library`	string	-	Target Plex library to sync into

letterboxd

Field	Type	Default	Description
`enabled`	bool	false	Enable Letterboxd integration
`sources`	list	[]	Letterboxd list sources to sync
`sources[].name`	string	-	Display name (becomes the Plex collection name)
`sources[].url`	string	-	Full or short Letterboxd list URL
`sources[].plex_library`	string	-	Target Plex library to sync into

tautulli

Field	Type	Default	Description
`enabled`	bool	false	Enable Tautulli analytics
`api_key`	string	null	Tautulli API key (prefer env var)
`base_url`	string	`http://localhost:8181`	Tautulli server URL
`collect_on_rotation`	bool	true	Collect analytics after each rotation
`collect_interval_hours`	int	24	Hours between analytics collection

seerr

Field	Type	Default	Description
`enabled`	bool	false	Enable Seerr integration
`api_key`	string	null	Seerr API key (prefer env var)
`base_url`	string	`http://localhost:5055`	Seerr server URL

anilist

Field	Type	Default	Description
`sources`	list	[]	AniList sources to sync
`sources[].name`	string	-	Display name (becomes the Plex collection name)
`sources[].url`	string	-	AniList user list URL or browse URL (e.g., `anilist://browse/top-100`)
`sources[].plex_library`	string	-	Target Plex library to sync into
`sources[].max_items`	int	100	Max items to fetch (10–500, only applies to browse lists)

tmdb

Field	Type	Default	Description
`enabled`	bool	false	Enable TMDb integration
`api_key`	string	null	TMDb API key (prefer env var)
`sources`	list	[]	TMDb list sources to sync
`sources[].name`	string	-	Display name (becomes the Plex collection name)
`sources[].url`	string	-	TMDb list URL (e.g., `https://www.themoviedb.org/list/123456`)
`sources[].plex_library`	string	-	Target Plex library to sync into

mal

Field	Type	Default	Description
`enabled`	bool	false	Enable MyAnimeList integration
`client_id`	string	null	MAL API client ID (prefer env var)
`sources`	list	[]	MAL list sources to sync
`sources[].name`	string	-	Display name (becomes the Plex collection name)
`sources[].url`	string	-	MAL list URL or seasonal URL (e.g., `mal://season/2026/spring`)
`sources[].plex_library`	string	-	Target Plex library to sync into

display

Field	Type	Default	Description
`group_display_mode`	string	grouped	How collection groups are arranged on the Plex homescreen: `grouped` (clustered by group) or `merged` (round-robin across groups)

logging

Field	Type	Default	Description
`level`	string	INFO	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`

Example Config​

Section Reference​

plex​

rotation​

Group Order​

groups​

auth​

trakt​

mdblist​

letterboxd​

tautulli​

seerr​

anilist​

tmdb​

mal​

display​

logging​