Moonbase stores each user's preferences on the server and shares them across every Moonfin client, so your setup follows you between devices. Change a setting on your phone, and your TV picks it up.
There is nothing to configure as a user. As long as the admin has Moonbase Sync enabled on the server, sync just works.
How it works at a glance
Each client keeps a local copy of your settings and pushes changes to the server.
On startup a client fetches the server copy and merges it with its local copy. If both sides changed the same setting, the local one wins.
Opening Moonfin on a new device with no local settings pulls everything from the server. This is how your setup carries over to a new client.
Clients that are open and connected pick up changes, theme updates, and admin messages live, without a restart.
Device profiles
Your settings live in a shared global profile that every device inherits. On top of that, you can override individual settings per device type: desktop, mobile, or tv. A device profile only stores the values you actually changed for that device, so everything you leave alone keeps flowing from global.
When a client asks for a setting, the server answers with the first value that's set, in this order:
The device profile (desktop, mobile, or tv)
The global profile
The admin default settings
If none of those set a value, the client falls back to its own built-in default.
Advanced: the settings envelope
Settings are stored per user as one JSON file on the server, in a profiled envelope. Data Locations covers exactly where it lives.
{
"schemaVersion": 2,
"lastUpdated": 1740200000000,
"lastUpdatedBy": "desktop",
"syncEnabled": true,
"global": { "...": "base settings that every device inherits" },
"desktop": { "...": "overrides for desktop only" },
"mobile": { "...": "overrides for mobile only" },
"tv": { "...": "overrides for TV only" }
}
Field
Type
Description
schemaVersion
int
2 for the profiled format. Older flat (v1) files are migrated automatically on load
lastUpdated
long
When the envelope was last saved, in epoch milliseconds
lastUpdatedBy
string
The client id that last wrote it
syncEnabled
bool
Whether server sync is on for this user
global
profile
Base values that all devices inherit
desktop, mobile, tv
profile
Sparse overrides that apply only on that device type
Valid profile names are global, desktop, mobile, and tv.
Advanced: startup and merge behavior
On startup a client pings /Moonfin/Ping to confirm the plugin is installed and sync is on, then fetches /Moonfin/Settings. What happens next depends on what already exists:
Local and server both exist, with a snapshot: a three-way merge. For each setting, if only one side changed, that change is kept. If both sides changed the same setting, the local value wins.
Local and server both exist, no snapshot: first sync on this client. Local wins, then the merged result is pushed back to the server.
Server only (fresh install or new browser): the server settings are restored locally.
Local only: the local settings are pushed to the server.
After merging, the result is saved as the new snapshot for next time. Every settings change also saves locally right away and, when the server is reachable, pushes to the server.
The settingsUpdated broadcast only fires when a save actually changed something, so a no-op save doesn't make other clients re-sync. Live updates only reach clients currently connected to the events stream (/Moonfin/Settings/Stream). Others catch up on their next startup.
Admin side
The dashboard's Defaults tab sets the admin default for every client setting, split into subtabs (General Style, Details Screen, Navigation, Home Screen, Home Sections, Libraries, Playback, Extras, and Integrations). A setting left on Not set (user decides) passes the user's own choice through.
Push Defaults to Existing Users updates the stored global values and emits a live update, so connected clients re-resolve immediately.
The sync toggle in the dashboard is labelled Moonbase Sync. Enabling it is required for the Seerr and ratings integrations.
Admin broadcasts and server messages are delivered over the same live stream, and also go out as push to devices with a registered token. See API Reference for the endpoints.
Advanced: file repair and quarantine
Plugin releases 1.9.1 through 2.0.0 could leave a user's settings file truncated if the server crashed or restarted mid-write, which broke sync for that user until their profile was reset. Current releases write these files atomically, and a repair pass runs at startup as the Moonfin Settings File Repair scheduled task (also runnable manually from Dashboard > Scheduled Tasks):
Healthy files are never touched.
Truncated settings files are repaired when a usable prefix survives, and the global profile usually comes back intact.
Anything unrecoverable is moved, never deleted, to plugins/configurations/Moonfin/quarantine/ (settings/, notifications/, seerr-sessions/ subfolders) with a UTC timestamp suffix, so support can inspect it later.
The task logs a per-store summary line (scanned / healthy / salvaged / recovered / quarantined).
The quarantine folder is safe to clear once affected users confirm their settings look right. On Emby the boot-time repair runs automatically after plugin startup, and the dashboard task there exists for manual re-runs.
Synced settings
Everything below can be set on global and optionally overridden per device profile. Names are the JSON property names. Not every client uses every setting yet: the server stores the full set, and each client reads and writes the ones it supports while preserving the rest untouched.
Integrations
Setting
Type
Description
seerrEnabled
bool
Enable Seerr integration
seerrApiKey
string
Seerr API key
seerrBlockNsfw
bool
Hide adult results from Seerr
seerrRows
object
Which Seerr discovery rows show and their order
mdblistEnabled
bool
Enable MDBList ratings
mdblistApiKey
string
MDBList API key
mdblistRatingSources
list
Which rating sources to pull from MDBList
mdblistShowRatingNames
bool
Show the rating source names
mdblistShowRatingBadges
bool
Show rating badges
tmdbApiKey
string
TMDB API key
tmdbEpisodeRatingsEnabled
bool
Enable per-episode ratings from TMDB
The jellyseerr* names (jellyseerrEnabled, jellyseerrApiKey, jellyseerrBlockNsfw, jellyseerrRows) are legacy aliases backed by the same values as their seerr* equivalents.
Seerr rows fields
Field
Type
Description
trendingMovies
bool
Show the trending movies row
trendingTv
bool
Show the trending TV row
popularMovies
bool
Show the popular movies row
popularTv
bool
Show the popular TV row
upcomingMovies
bool
Show the upcoming movies row
upcomingTv
bool
Show the upcoming TV row
rowOrder
list
The order of the Seerr rows
Navbar and appearance
Setting
Type
Description
navbarPosition
string
Navbar placement (top, left, bottom)
navbarColor
string
Navbar color
navbarOpacity
int
Navbar opacity
navbarAlwaysExpanded
bool
Keep the navbar expanded
bottomNavbarStyle
string
Style of the phone and tablet bottom navbar (dock, split, strip)
bottomNavbarTabs
list
Up to three tabs between Home and You on the bottom navbar (search, libraries, favorites, genres, liveTv, discover, folders). Empty lets each device pick them from the nav buttons
focusColor
string
Accent color for focused items
visualTheme
string
Selected built-in theme
customThemeId
string
Selected custom theme id
watchedIndicator
string
Style of the watched indicator
cardFocusExpansion
bool
Expand cards when focused
posterSize
string
Poster size
seasonalSurprise
string
Seasonal particle effect on Home (none, snow, christmas, fireworks, confetti, petals, fireflies, leaves, halloween)
seasonalDensity
string
How many seasonal particles are on screen at once (light, normal, heavy)
seasonalRowEnabled
bool
Show the seasonal Home row of holiday movies. Off by default
seasonalRowCountry
string
Country the seasonal row follows: auto, an ISO alpha-2 code (US, CA) or other
seasonalRowHiddenHolidays
string[]
Holidays the user switched off (newYear, valentines, easter, pride, halloween, thanksgiving, christmas, lunarNewYear, diwali)
backdropEnabled
bool
Show backdrops
browsingBlur
string
Blur behind browsing screens
showServerMessagesButton
bool
Show the server messages button in the navigation. Off by default, and hidden automatically on clients that don't support messages
Detail screen sections to hide, such as cast, chapters, extras or the Seerr sections. A hidden section is hidden in every detail screen style
Media bar
Setting
Type
Description
desktopMediaBarProvider
string
Which provider backs the desktop media bar
mediaBarMode
string
Media bar mode
mediaBarSourceType
string
Source type (library or collection)
mediaBarContentType
string
Which item types the media bar shows (both, movies, tvshows)
mediaBarLibraryIds
list
Library ids feeding the media bar
mediaBarCollectionIds
list
Collection ids feeding the media bar
mediaBarExcludedGenres
list
Genres to exclude
mediaBarItemCount
int
Number of items
mediaBarOpacity
int
Overlay opacity
mediaBarOverlayColor
string
Overlay color
mediaBarAutoAdvance
bool
Auto-advance slides
mediaBarIntervalMs
int
Auto-advance interval in milliseconds
mediaBarTrailerPreview
bool
Play trailer previews
mediaBarTrailerAudio
bool
Enable trailer audio
episodePreviewEnabled
bool
Enable episode previews
previewAudioEnabled
bool
Enable preview audio
Home rows
Setting
Type
Description
homeSections
list
The full home layout, including dynamic plugin sections. Newer clients prefer this
homeRowOrder
list
The legacy ordered list of built-in rows
homeRowsStyle
string
Home rows rendering style
homeRowsImageType
string
Home rows image type (poster, thumb, banner)
homeRowsImageTypeOverride
bool
Override the home rows image type
homeImageTypeContinueWatching
string
Image type for the Continue Watching row
homeImageUseSeriesImage
bool
Use the series image instead of the episode image
fullScreenRows
bool
Full-screen home rows
mergeContinueWatchingNextUp
bool
Merge Continue Watching with Next Up
nextUpMaxDays
int
How many days a show stays in Next Up after you last watched it
displayFavoritesRows
bool
Show favorites rows
displayCollectionsRows
bool
Show collections rows
displayGenresRows
bool
Show genres rows
displaySeerrRows
bool
Show Seerr rows
displayPlaylistsRows
bool
Show playlists rows
displayAudioRows
bool
Show audio rows
favoritesRowSortBy
string
Sort order for favorites rows
collectionsRowSortBy
string
Sort order for collections rows
genresRowSortBy
string
Sort order for genres rows
genresRowItemFilter
string
Item filter for genres rows
playlistsRowSortOrder
string
Sort order for playlists rows
audioRowsSortOrder
string
Sort order for audio rows
favoritesRowSortOrder
string
Ascending or descending for favorites rows
collectionsRowSortOrder
string
Ascending or descending for collections rows
genresRowSortOrder
string
Ascending or descending for genres rows
displayStudiosRows
bool
Show the studios row
studiosRowSortBy
string
Sort key for the studios row
studiosRowSortOrder
string
Ascending or descending for the studios row
studiosRowSelectedIds
string
The studios chosen for the row
recentlyReleasedSeriesType
string
Whether the Recently Released row lists series, seasons, or episodes
hideHomeMediaDescription
bool
Hide episode descriptions on home rows, for spoiler-free browsing
mediaTypeBadgeBehavior
string
When the media type badge shows on home row cards
modernHomeRowsPadding
int
Vertical space between rows
classicHomeRowsPadding
int
Vertical space between rows
modernCardsOnMyMediaRow
bool
Display customizable posters that expand on focus. Disable to always show landscape thumbnail
homeRowInfoOverlay
bool
Show title and metadata when browsing home rows
nextUpBehavior
string
Extended shows a full card with episode artwork and description. Minimal shows a compact countdown overlay. Disabled hides the prompt entirely
nextUpTimeout
int
How long the Next Up prompt stays on screen
stillWatchingBehavior
string
Still Watching prompt, and after how many consecutive episodes it appears (disabled, short_, medium, long_, veryLong)
Home sections fields
Field
Type
Description
kind
string
Section kind, built-in or a dynamic plugin section
type
string
The row key for built-in sections
enabled
bool
Whether the section shows
order
int
Position of the section on the home screen
serverId
string
Owning server for multi-server setups
pluginSource
string
Source plugin for dynamic sections
pluginSection
string
The plugin's section identifier
pluginAdditionalData
string
Extra data the plugin section needs
pluginDisplayText
string
Display label for the plugin section
Custom home rows propagate across device profiles. A row created on one profile shows up on the others in a disabled state, edits to it propagate, and deleting it removes it everywhere.
Since You Watched and Rewatch rows
Setting
Type
Description
displaySinceYouWatchedRows
bool
Show Since You Watched rows
sinceYouWatchedSource
string
Source for those rows
sinceYouWatchedSourceType
string
Source type
sinceYouWatchedSourceItem
string
Specific source item
sinceYouWatchedNumRows
int
How many rows to show
sinceYouWatchedIncludeWatched
bool
Include already-watched items
displayRewatchRow
bool
Show the rewatch row
rewatchSortBy
string
Sort order for the rewatch row
rewatchIncludeMovies
bool
Include movies
rewatchIncludeShows
bool
Include shows
rewatchIncludeCollections
bool
Include collections
sinceYouWatched1Enabled
bool
Since You Watched Row 1
sinceYouWatched2Enabled
bool
Since You Watched Row 2
sinceYouWatched3Enabled
bool
Since You Watched Row 3
sinceYouWatched4Enabled
bool
Since You Watched Row 4
sinceYouWatched5Enabled
bool
Since You Watched Row 5
Library and playback
Setting
Type
Description
oledMode
string
True black backgrounds for OLED screens
mergeRecentRowsByType
bool
Merge the Recently Added and Recently Released rows by type
collectionsRowShowEpisodes
bool
Show individual episodes in the collections row
playlistsRowShowEpisodes
bool
Show individual episodes in the playlists row
mediaBarTrailerCaptions
bool
Show captions on media bar trailer previews
enableMultiServerLibraries
bool
Aggregate libraries across servers
enableFolderView
bool
Enable folder view
showBookDiscoverTab
bool
The discovery tab in book and audiobook libraries, which browses titles from Open Library and LibriVox
confirmExit
bool
Ask before exiting
blockedRatings
list
Content ratings to hide
themeMusicEnabled
bool
Enable theme music
themeMusicOnHomeRows
bool
Play theme music on home rows
themeMusicVolume
int
Theme music volume
themeMusicLoop
bool
Loop theme music
hiddenContinueWatchingItems
string
Items hidden from Continue Watching
hiddenNextUpSeries
string
Series hidden from Next Up
personalRatingStyle
string
Whether your own rating reads as a like, five stars, or a score out of ten
cinemaModeEpisodesEnabled
bool
Run Cinema Mode pre-rolls before TV episodes as well as movies
mediaSegmentActions
string
The skip action chosen for each media segment type
mediaSegmentAutoHide
string
Whether and when the skip button hides itself
playerSwipeGestures
bool
Volume and brightness swipe gestures in the mobile player
desktopScrollSensitivity
int
Scroll wheel and trackpad sensitivity on desktop
crashReportsEnabled
bool
Whether captured crash reports are uploaded to the server. Capture itself is always local
defaultAudioLanguage
string
Preferred audio language as an ISO 639-2 code, or auto to follow the server
fallbackAudioLanguage
string
Audio language to try when no track matches the preferred one. Empty means none
defaultSubtitleLanguage
string
Preferred subtitle language as an ISO 639-2 code. Empty means none
fallbackSubtitleLanguage
string
Subtitle language to try when no track matches the preferred one. Empty means none