Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rivenmedia/riven-ts/llms.txt

Use this file to discover all available pages before exploring further.

Riven is configured entirely through environment variables. Every core setting is prefixed with RIVEN_SETTING__ followed by the camelCase setting name. Plugin-specific settings use a separate RIVEN_PLUGIN_SETTING__ prefix. All variables are typically collected in a .env file passed to Docker via env_file.
Riven validates every setting at startup using Zod schemas. If a required variable is missing or a value fails validation, the process exits immediately with a clear error message. Set RIVEN_SETTING__printConfigurationOnStartup=true to log the fully-parsed configuration on boot — useful for debugging.

​
Database

​
RIVEN_SETTING__databaseUrl
string
required
PostgreSQL connection URL. The host must be the Docker service name (e.g. riven-db), not localhost — localhost inside the container refers to the Riven container itself.
RIVEN_SETTING__databaseUrl="postgres+psycopg2://riven:CHANGEME@riven-db:5432/riven"
​
RIVEN_SETTING__redisUrl
string
required
Redis connection URL. Like the database, use the Docker service name as the host.
RIVEN_SETTING__redisUrl="redis://riven-cache:6379"
​
RIVEN_SETTING__databaseDebugLogging
boolean
default:"false"
Enable verbose SQL query logging from the ORM. Useful when diagnosing slow queries or migration issues. Generates significant log volume — keep disabled in production.
​
RIVEN_SETTING__databaseSslRootCert
string
File path to the SSL root certificate for the database connection. The file is read at startup and its contents used to establish a TLS connection. Required when connecting to managed PostgreSQL services that enforce SSL (e.g. RDS, Neon, Supabase).
​
RIVEN_SETTING__databaseSslCert
string
File path to the SSL client certificate for mutual TLS authentication.
​
RIVEN_SETTING__databaseSslKey
string
File path to the SSL private key for mutual TLS authentication.

​
Virtual File System (VFS)

​
RIVEN_SETTING__vfsMountPath
string
required
The path inside the container where Riven mounts its FUSE virtual file system. This must match the container-side path of your Docker volume mount — not the host path.
# docker-compose.yml volume:  /mnt/riven:/mount:rshared,z
RIVEN_SETTING__vfsMountPath="/mount"
Setting this to the host path (e.g. /mnt/riven) instead of the container-side path (/mount) is a common misconfiguration. The VFS will mount to a path that doesn’t exist in the container and files will never appear on the host.
​
RIVEN_SETTING__vfsForceMount
boolean
default:"true"
When true, Riven attempts to unmount the mount point before remounting on startup. This ensures a clean state if the previous run exited uncleanly. Disable only if you manage the mount lifecycle manually.
​
RIVEN_SETTING__vfsDebugLogging
boolean
default:"false"
Enable verbose logging for VFS operations. Useful for diagnosing mount or file-visibility issues. Generates very high log volume.

​
GraphQL API

​
RIVEN_SETTING__gqlHost
string
default:"localhost"
The interface the GraphQL HTTP server binds to. The default localhost means the server is only reachable from within the container. Set to 0.0.0.0 to bind to all interfaces so the API is reachable from the Docker host and through a reverse proxy.
RIVEN_SETTING__gqlHost="0.0.0.0"
​
RIVEN_SETTING__gqlPort
number
default:"3000"
The port the GraphQL server listens on. If you change this, update your ports mapping in docker-compose.yml to match.
RIVEN_SETTING__gqlPort="3000"

​
Logging

​
RIVEN_SETTING__logLevel
string
default:"info"
Minimum severity level for log output. Messages below this level are suppressed.Accepted values (most to least verbose): silly · debug · verbose · http · info · warn · error
# Recommended for production
RIVEN_SETTING__logLevel="warn"

# Recommended for debugging
RIVEN_SETTING__logLevel="debug"
​
RIVEN_SETTING__logDirectory
string
default:"./logs"
Directory where log files are written when the file transport is enabled. The container default is /app/logs, which is bind-mounted to ./logs on the host in the reference compose file.
​
RIVEN_SETTING__loggingEnabled
boolean
default:"true"
Master switch for all logging. Setting this to false silences all output regardless of logLevel.
​
RIVEN_SETTING__enabledLogTransports
JSON array
default:"[\"console\",\"file\"]"
Which log transports are active. Accepts a JSON array containing "console", "file", or both.
# Console only (no log files written to disk)
RIVEN_SETTING__enabledLogTransports='["console"]'
​
RIVEN_SETTING__logShowStackTraces
boolean
default:"true"
Whether to include full stack traces when unexpected errors occur. Disable to reduce log noise if errors are known and benign.

​
Plugins

​
RIVEN_SETTING__enabledPlugins
JSON array
default:"[]"
A JSON array of plugin names to activate. Only plugins listed here are loaded at startup.Available plugin names: comet · jellyfin · listrr · mdblist · notifications · plex · seerr · stremthru · subdl · tmdb · torrentio · tvdb
RIVEN_SETTING__enabledPlugins='["seerr","stremthru","torrentio","plex","tmdb","tvdb"]'

​
Ranking

​
RIVEN_SETTING__rankingConfigPath
string
default:"./riven-ranking-config.json"
Path inside the container to the JSON file that controls how Riven scores and ranks scraped torrents. The file is auto-generated with defaults on first startup if it does not exist. The default resolves to /app/riven-ranking-config.json inside the container.
# Only needed if you want to store the config at a non-default location
RIVEN_SETTING__rankingConfigPath="/app/riven-ranking-config.json"
If you bind-mount this path from the host, create the file before starting the container — otherwise Docker will create a directory at that path instead of a file and Riven will fail to write the config.

​
Scraping

​
RIVEN_SETTING__maximumFailedAttempts
number
default:"10"
Maximum number of scrape attempts before Riven gives up on an item. Set to 0 to allow unlimited attempts (not recommended — items that can never be scraped will consume queue resources indefinitely). Must be between 0 and 10.
​
RIVEN_SETTING__scrapeCooldownHours
JSON array
default:"[2,6,24]"
Cooldown periods in hours applied after consecutive failed scrape attempts. Format: [after >2 failures, after >5 failures, after >10 failures].
RIVEN_SETTING__scrapeCooldownHours="[2,6,24]"
​
RIVEN_SETTING__preferSeasonPacks
boolean
default:"false"
When true, Riven prefers to download complete season packs over individual episode files when both are available.
​
RIVEN_SETTING__attemptUnknownDownloads
boolean
default:"false"
When true, Riven attempts to download torrents whose file contents cannot be verified without downloading first. Enabling this improves coverage for hard-to-find items but degrades overall performance by increasing failed download attempts.
​
RIVEN_SETTING__dubbedAnimeOnly
boolean
default:"false"
When true, Riven only scrapes dubbed versions of anime titles.
​
RIVEN_SETTING__minimumAverageBitrateMovies
number
Minimum average bitrate (in kbps) required for movie downloads. Torrents below this threshold are skipped. Optional — no minimum is enforced by default.
​
RIVEN_SETTING__minimumAverageBitrateEpisodes
number
Minimum average bitrate (in kbps) required for episode downloads. Optional — no minimum is enforced by default.

​
Scheduling

​
RIVEN_SETTING__scheduleOffsetMinutes
number
default:"30"
How many minutes to wait after an item’s scheduled air date before attempting to re-index it. A 30-minute buffer accounts for encoder/uploader delays.
​
RIVEN_SETTING__unknownAirDateOffsetDays
number
default:"7"
When an episode has no known air date, Riven adds this many days to the current date to estimate a future release date for scheduling purposes.

​
Shutdown

​
RIVEN_SETTING__shutdownTimeoutSeconds
number
default:"30"
How long Riven waits for in-flight jobs to complete during a graceful shutdown before forcefully terminating. Increase this if you have long-running plugin operations.

​
Debugging

​
RIVEN_SETTING__printConfigurationOnStartup
boolean
default:"false"
When true, the fully-parsed and validated configuration object is printed to the log at startup. Useful for verifying that environment variables are being read correctly. Disable in production as it may log sensitive values such as API keys.

​
Danger Zone

The following settings permanently destroy data. They exist for development and disaster-recovery scenarios only. Never set them to true in a production environment.
​
RIVEN_SETTING__unsafeWipeRedisOnStartup
boolean
default:"false"
When true, all Redis data is flushed on every application startup. This cancels all in-flight jobs. Safe only during development when you want a clean queue state.
​
RIVEN_SETTING__unsafeWipeDatabaseOnStartup
boolean
default:"false"
When true, the database is dropped and recreated on every application startup. This deletes your entire library. Use only in development.

​
Plugin Settings

Plugin-specific settings follow a separate naming convention: 
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_<PLUGIN_NAME>__<settingKey>=value
Where <PLUGIN_NAME> is the uppercase plugin name and <settingKey> is the camelCase setting key defined by that plugin.

​
Examples

.env.riven
# TMDB metadata plugin — add "tmdb" to enabledPlugins to activate
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey="your-tmdb-api-key"

# StremThru debrid connector — set the key for your debrid service
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_STREMTHRU__realdebridApiKey="your-rd-key"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_STREMTHRU__alldebridApiKey="your-ad-key"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_STREMTHRU__torboxApiKey="your-tb-key"

# Seerr / Overseerr content request source
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_SEERR__url="http://seerr:5055"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_SEERR__apiKey="your-seerr-api-key"

# Plex media server
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_PLEX__plexToken="your-plex-token"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_PLEX__plexServerUrl="http://plex:32400"

# Jellyfin media server
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_JELLYFIN__jellyfinUrl="http://jellyfin:8096"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_JELLYFIN__jellyfinApiKey="your-jellyfin-api-key"
Plugin names are case-sensitive in the environment variable name. REPO_PLUGIN_TMDB is correct; REPO_PLUGIN_tmdb will not be recognized.

​
Minimal Production .env

A trimmed .env file covering the most common single-server deployment:
.env.riven
# Database connections
RIVEN_SETTING__databaseUrl="postgres+psycopg2://riven:CHANGEME@riven-db:5432/riven"
RIVEN_SETTING__redisUrl="redis://riven-cache:6379"

# VFS — must match the container-side volume mount path
RIVEN_SETTING__vfsMountPath="/mount"

# Bind the GraphQL API to all interfaces (required for reverse proxy access)
RIVEN_SETTING__gqlHost="0.0.0.0"

# Log level: use "warn" in production to reduce noise
RIVEN_SETTING__logLevel="warn"

# Plugins to enable
RIVEN_SETTING__enabledPlugins='["seerr","stremthru","torrentio","plex","tmdb","tvdb"]'

# Plugin API keys
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey="your-tmdb-api-key"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_STREMTHRU__realdebridApiKey="your-rd-key"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_SEERR__url="http://seerr:5055"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_SEERR__apiKey="your-seerr-key"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_PLEX__plexToken="your-plex-token"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_PLEX__plexServerUrl="http://plex:32400"

Build docs developers (and LLMs) love

Get started for freeTalk to us