Configuration

Almost everything about a running Credenza server is set in the browser, under Settings → Server: libraries, users, transcoding, metadata providers and more. This page covers what you can set outside the browser, before the server starts — the database connection, the port, a first administrator, and the defaults behind the settings pages.

Where configuration goes

Every option is an environment variable whose name is its path with double underscores between the parts, such as MediaServer__Database__ConnectionString. Restart the server after changing one.

Docker Compose — add it under the credenza service’s environment: in docker-compose.yml, then run docker compose up -d:

docker-compose.yml

services:
  credenza:
    environment:
      MediaServer__Updates__Enabled: "false"

Linux — add it to /etc/credenza/credenza.env, one NAME="value" per line, then restart the service. Upgrades never overwrite this file.

/etc/credenza/credenza.env

MediaServer__Updates__Enabled="false"

sudo systemctl restart credenza

A few value formats come up repeatedly:

Kind	Format	Example
Duration	hh:mm:ss, or d.hh:mm:ss for days	00:05:00 is five minutes, 1.00:00:00 is a day
List	One variable per entry, numbered from 0	MediaServer__Library__VideoExtensions__0=".mkv"
True or false	true or false	MediaServer__Mcp__Enabled="false"

Settings saved in the browser win

Most options below are only defaults. Where a settings page has a field for the same thing, a value saved in the browser takes precedence over configuration, and it is stored in the database, so it survives restarts and upgrades.

Each of those fields shows the configured value as its placeholder, with a note underneath:

• Using the configured default (…) — nothing is saved in the browser, so the configuration value applies.
• Leave blank to go back to … — a value is saved in the browser and overrides the configuration. Clear the field and save to hand control back to configuration.

So if you change an environment variable and nothing happens, check whether the same setting has a value saved on its settings page. The tables below give the settings page for each option that has one.

Required

Variable	Default	What it does
MediaServer__Database__ConnectionString	none	The PostgreSQL connection string. The Compose file and the Linux installer both set it for you. The database needs the pgmq and pg_search extensions — see Installation
ASPNETCORE_URLS	http://+:8080 (Docker), http://0.0.0.0:8080 (Linux)	The address and port the server listens on. To move a Docker install to another port, change the host side of ports: instead

The database schema is created and upgraded automatically each time the server starts.

Server and first administrator

Variable	Default	Settings page	What it does
MediaServer__ApplicationName	mediaserver	General → Server name	What the server calls itself
MediaServer__PublicUrl	none	General → Public address	The address people outside the machine use, such as https://media.example.com. Links the server hands out, like invite links, are built from it
MediaServer__Auth__InitialUser__Username	none	—	Creates an administrator with this username on first start
MediaServer__Auth__InitialUser__Password	none	—	That administrator’s password, at least 12 characters
MediaServer__Auth__Invites__MaximumUses	25	—	The most people a single invite link can let in
MediaServer__Auth__Invites__MaximumLifetimeDays	30	—	The longest an invite link can stay valid, in days

The initial administrator is optional. Without it, the server asks for one in the browser on first visit — see First run. It is created only when the database has no accounts at all, so changing it later does not change anyone’s password; use Settings → User → Account for that.

Behind a reverse proxy

If something in front of Credenza terminates HTTPS — nginx, Caddy, Traefik, a tunnel — set Public address and tick Behind a reverse proxy on Settings → Server → General. With it on, the server trusts the proxy’s X-Forwarded-Proto header, so the sign-in cookie is marked Secure.

Variable	Default	Settings page	What it does
MediaServer__ReverseProxy__Enabled	false	General → Behind a reverse proxy	Honour X-Forwarded-Proto
MediaServer__ReverseProxy__KnownProxies__0	none	—	Only accept the header from these proxy IP addresses. When neither this nor KnownNetworks is set, it is accepted from any address
MediaServer__ReverseProxy__KnownNetworks__0	none	—	Only accept the header from these networks, in CIDR form such as 172.18.0.0/16
MediaServer__ReverseProxy__ForceDisable	false	—	Force the setting off, whatever is saved in the browser

Locked out after ticking Behind a reverse proxy?

If the proxy sends X-Forwarded-Proto: https but you reach the server over plain HTTP, your browser refuses the Secure cookie and you cannot stay signed in to turn the setting back off. Set MediaServer__ReverseProxy__ForceDisable=true, restart, sign in and untick it, then remove the variable and restart again.

Transcoding

These are the defaults behind Settings → Server → Transcoding. See How playback works and Hardware acceleration for what they mean in practice.

Variable	Default	Settings page field	What it does
MediaServer__Streaming__Encoder	auto	Hardware when available / Software only	auto uses a working hardware encoder if there is one. Or name one: libx264 (software), nvenc, vaapi, videotoolbox. One that is not usable falls back to software, and the page says why
MediaServer__Streaming__MaxConcurrentSessions	4	Concurrent streams	How many transcodes can run at once. 0 means no limit
MediaServer__Streaming__EncoderPreset	veryfast	Encoder preset	The software encoder’s speed–quality trade-off, from ultrafast to placebo
MediaServer__Streaming__EncoderCrf	21	Quality (CRF)	Software encoding quality; lower is better and larger
MediaServer__Streaming__MaxRate	8M	Bitrate ceiling	The highest video bitrate a transcode may use
MediaServer__Streaming__AudioBitrate	192k	Audio bitrate	The bitrate of transcoded audio
MediaServer__Streaming__SegmentDuration	6	Segment length	Seconds of video per streaming segment
MediaServer__Streaming__IdleTimeout	00:05:00	Idle timeout	How long an abandoned stream keeps transcoding before it is stopped
MediaServer__Streaming__SegmentReadyTimeout	00:00:30	Segment timeout	How long a request for a segment waits for the transcoder before giving up
MediaServer__Streaming__LookaheadTolerance	3	Lookahead tolerance	How far ahead of the transcoder, in segments, a player can ask before the transcode restarts at the new position
MediaServer__Streaming__WorkDirectory	/tmp/credenza in Docker, /var/cache/credenza/transcode with the Linux packages	Storage → Transcoding scratch	Where transcoded segments are written while a stream plays
MediaServer__Streaming__NvencMaxSessions	2	NVENC session limit	How many NVIDIA hardware transcodes can run at once
MediaServer__Streaming__VaapiDevice	/dev/dri/renderD128	VAAPI device	The render device used for AMD and Intel hardware encoding

ffmpeg

By default Credenza uses whichever ffmpeg and ffprobe are on the server’s PATH, which is what both install methods set up.

Variable	Default	Settings page field	What it does
MediaServer__Ffmpeg__Path	ffmpeg on the PATH	General → ffmpeg path	A specific ffmpeg to use
MediaServer__Ffmpeg__ProbePath	ffprobe on the PATH	General → ffprobe path	A specific ffprobe to use

Scanning

These are the defaults behind Settings → Server → Scanning. A list you set replaces the built-in one rather than adding to it.

Variable	Default	Settings page field	What it does
MediaServer__Library__VideoExtensions__0 …	.mkv .mp4 .m4v .avi .mov .ts .webm	Video file types	Which files film and television scans pick up
MediaServer__Library__ExcludedDirectoryNames__0 …	extras, featurettes, behind the scenes, deleted scenes, trailers, samples, @eaDir	Folders to skip	Folder names a scan never looks inside
MediaServer__Library__WatchdogInterval	00:05:00	Stuck-scan check	How often the server looks for a scan that has stopped making progress
MediaServer__Library__ScanDeadline	1.00:00:00	Scan deadline	How long a scan may stay running before it is marked failed
MediaServer__Library__GameExtensions__<System>__0 …	see below	—	Which files a games scan picks up for one console

For GameExtensions, <System> is one of Nes, Snes, Nintendo64, GameBoy, GameBoyColor or GameBoyAdvance. Setting a list for one console leaves the others at their defaults:

Console	Default file types
Nes	.nes .fds .unf .unif
Snes	.sfc .smc .swc .fig
Nintendo64	.z64 .v64 .n64
GameBoy	.gb
GameBoyColor	.gbc
GameBoyAdvance	.gba

Metadata

Provider credentials are usually entered on Settings → Server → Metadata, but they can be supplied as configuration instead — useful when you manage secrets outside the browser.

Variable	Default	Settings page field	What it does
MediaServer__Metadata__ApiReadAccessToken	none	TMDB read access token	Your TMDB API Read Access Token, for film and television details and artwork
MediaServer__Metadata__ArtworkDirectory	credenza/artwork in the data folder	Storage → Artwork cache	Where downloaded posters, backdrops and headshots are kept
MediaServer__Metadata__Language	en-US	—	The language TMDB answers in, as a language and region code such as fr-FR
MediaServer__Metadata__ProxyUrl	none	Proxy address	A proxy for every outbound request to metadata providers and the update check: an http, https, socks4, socks4a or socks5 address. If it is set but unusable, those requests stop rather than going direct
MediaServer__Metadata__ScreenScraper__DevId	Credenza’s own	Developer id	Your own ScreenScraper developer credentials, used instead of the ones Credenza comes with
MediaServer__Metadata__ScreenScraper__DevPassword	none	Developer password
MediaServer__Metadata__ScreenScraper__Username	none	ScreenScraper username	Your own ScreenScraper account, optional
MediaServer__Metadata__ScreenScraper__Password	none	ScreenScraper password
MediaServer__Metadata__ScreenScraper__Language	en	—	The language ScreenScraper answers in, falling back to English
MediaServer__Metadata__ScreenScraper__Region	us	—	The region ScreenScraper answers for
MediaServer__Metadata__Igdb__ClientId	none	Twitch client id	IGDB credentials, which come from a Twitch developer application
MediaServer__Metadata__Igdb__ClientSecret	none	Twitch client secret

When no outbound proxy is set, requests follow the machine’s own HTTP_PROXY environment variable if it has one.

Games

Limits on what a player’s browser can store on the server while playing. See Saves.

Variable	Default	What it does
MediaServer__Games__SaveDirectory	credenza/game-saves in the data folder	Where saves and save states are kept. Also moved at Storage → Game saves
MediaServer__Games__MaxSaveBytes	1048576 (1 MiB)	The largest in-game save file accepted
MediaServer__Games__MaxStateBytes	16777216 (16 MiB)	The largest save state accepted
MediaServer__Games__MaxScreenshotBytes	2097152 (2 MiB)	The largest screenshot stored with a save state

Update checks

The server checks credenza.tv for a newer release at startup and then on a schedule, and tells administrators when one is out — see Updating. The request carries nothing about your server.

Variable	Default	What it does
MediaServer__Updates__Enabled	true	Set to false to never check. The Updates section of Settings → Server → General then says it is switched off
MediaServer__Updates__Interval	12:00:00	How often to check. At least one minute

Logs

Credenza writes its log as JSON files, one per day, which Settings → Server → Logs reads back — see Logs.

Variable	Default	What it does
MediaServer__Logging__Directory	/data/logs (Docker), /var/log/credenza (Linux)	Where log files are written. Also moved at Storage → Logs
MediaServer__Logging__RetainedFileCountLimit	14	How many log files to keep before the oldest is deleted
MediaServer__Logging__FileSizeLimitBytes	67108864 (64 MiB)	The size at which a day’s log file is closed and a new one started
MediaServer__Logging__Enabled	true	Set to false to write no log files
MediaServer__Logging__Loki__Enabled	false in both installs	Also send the log to a Grafana Loki server
MediaServer__Logging__Loki__Uri	http://localhost:3100	The Loki server’s address
Logging__LogLevel__Default	Information	The least severe level written: Debug, Information, Warning or Error

MCP endpoint

The Model Context Protocol endpoint lets an AI assistant help fix unmatched items — see MCP.

Variable	Default	Settings page field	What it does
MediaServer__Mcp__Enabled	true	Integrations → Answer on the MCP endpoint	Whether the endpoint answers
MediaServer__Mcp__Path	/mcp	—	The path it is served at. Must begin with /
MediaServer__Mcp__MaxResults	50	—	The most results one tool call returns

Folders

Every folder Credenza writes to can be moved two ways: with a variable here, or with Change on its row at Settings → Server → Storage. As everywhere else, a folder chosen on the page wins over the variable, and Use default on the page hands it back. The page always shows the folder actually in use, whichever of the two chose it.

Variable	Default	What goes there
MediaServer__DataDirectory	/data (Docker), /var/lib (Linux)	The data folder. The defaults below that say “in the data folder” are under it. It has no field on the page, because moving it would move every folder still at its default
MediaServer__Games__SaveDirectory	credenza/game-saves in the data folder	Game saves and save states
MediaServer__Auth__SignInKeysDirectory	credenza/sign-in-keys in the data folder	The keys that keep people signed in
MediaServer__Logging__Directory	/data/logs (Docker), /var/log/credenza (Linux)	Log files
MediaServer__Backups__Directory	credenza/backups in the data folder	Exported backups
MediaServer__Metadata__ArtworkDirectory	credenza/artwork in the data folder	The artwork cache
MediaServer__Streaming__WorkDirectory	/tmp/credenza (Docker), /var/cache/credenza/transcode (Linux)	Transcoding scratch

A relative path in any of these variables is taken relative to the folder Credenza is installed in (/app in Docker, /usr/lib/credenza with the Linux packages), never the directory it was started from. A folder chosen on the page must be an absolute path.

Two places are listed on the Storage page but can’t be moved from it: the database, which is wherever MediaServer__Database__ConnectionString points, and the web app, the built interface that ships with Credenza and is replaced on every upgrade.

Moving a folder doesn’t carry its contents across, except for the sign-in keys, which are copied so nobody is signed out. Copy game saves yourself before moving them, or they will appear to be gone.

Sign-in keys before 2026-10

Earlier releases kept the sign-in keys in the server’s home folder (~/.aspnet/DataProtection-Keys). The first start of a newer release copies them into the data folder by itself, so nobody is signed out. In Docker, that also means you no longer need HOME: /data to keep them across upgrades.