Configure RivenVFS Filesystem and Library Profiles

The Riven Virtual Filesystem (RivenVFS) is the layer between your debrid service and your media server. When a torrent is confirmed available on your debrid provider, the VFS creates a virtual directory tree at mount_path that your media server can browse and stream from directly. No data is downloaded to disk — the VFS streams chunks on demand and caches them in RAM. All filesystem configuration lives under the filesystem key in AppModel.

Mount path

filesystem.mount_path

string

default:"\"/path/to/riven/mount\""

Absolute path where the VFS is mounted. This directory must exist on the host before Riven starts. When running in Docker, it must be a bind mount shared with your media server container so that both can see the same FUSE filesystem.

{
  "filesystem": {
    "mount_path": "/mnt/riven"
  }
}

The mount path must be a shared bind mount between the Riven container and your media server container. Use rslave propagation so that FUSE mounts created inside the Riven container propagate to the host and to other containers. Without this, your media server will see an empty directory.

Cache settings

The VFS uses an in-memory cache to store recently-read chunks, allowing fast seeking and re-reads without hitting the debrid service repeatedly. The cache lives in RAM (defaulting to /dev/shm), so it is fast but ephemeral across restarts.

filesystem.cache_dir

string

default:"\"/dev/shm/riven-cache\""

Directory for storing cached chunk data. /dev/shm is a RAM-backed tmpfs on Linux and is the recommended location for lowest latency. Set to a regular directory path if you prefer disk-backed caching.

filesystem.cache_max_size_mb

integer

default:"10240"

Maximum total cache size in megabytes. The default is 10,240 MB (10 GiB). When the cache reaches this limit, chunks are evicted according to the cache_eviction policy. Set to 0 for no size limit.

filesystem.cache_ttl_seconds

integer

default:"7200"

Cache time-to-live in seconds. The default is 7,200 seconds (2 hours). When using the TTL eviction policy, chunks older than this value are evicted. When using LRU, this value is still tracked but eviction is primarily driven by size.

filesystem.cache_eviction

string

default:"\"LRU\""

Cache eviction policy. One of:

LRU — Least Recently Used. Evicts the chunk that was accessed least recently when the cache is full. Best for typical streaming workloads where recently-watched content is likely to be re-read.
TTL — Time To Live. Evicts chunks that have exceeded cache_ttl_seconds regardless of access frequency.

filesystem.cache_metrics

boolean

default:"true"

Log cache hit/miss metrics periodically. Useful for tuning cache_max_size_mb — if you see a high miss rate, increase the cache size.

Naming templates

Riven generates virtual directory and file names from Python format strings. Templates use {variable} placeholders; double curly braces {{ and }} produce literal brace characters in the output (e.g., {{tmdb-{tmdb_id}}} renders as {tmdb-123456}).

Movie templates

filesystem.movie_dir_template

string

default:"\"{title} ({year}) {{tmdb-{tmdb_id}}}\""

Template for movie directory names.Available variables: title, year, tmdb_id, imdb_id, resolution, codec, hdr, audio, quality, is_remux, is_proper, is_repack, is_extended, is_directors_cut, containerExamples:

{title} ({year}) → Inception (2010)
{title} ({year}) [{resolution}] → Inception (2010) [1080p]
{title} ({year}) {{tmdb-{tmdb_id}}} → Inception (2010) {tmdb-27205}

filesystem.movie_file_template

string

default:"\"{title} ({year})\""

Template for movie file names, without extension (the extension is derived from the actual file).Available variables: title, year, tmdb_id, imdb_id, resolution, codec, hdr, audio, quality, remux, proper, repack, extended, directors_cut, editionFlag variables (remux, proper, repack, extended, directors_cut, edition) expand to a human-readable string when the flag is set, and to an empty string when not set.Examples:

{title} ({year}) → Inception (2010).mkv
{title} ({year}) {edition} [{resolution}] {remux} → Inception (2010) Extended Director's Cut [2160p] REMUX.mkv

Show templates

filesystem.show_dir_template

string

default:"\"{title} ({year}) {{tvdb-{tvdb_id}}}\""

Template for the top-level show directory.Available variables: title, year, tvdb_id, imdb_idExamples:

{title} ({year}) → Breaking Bad (2008)
{title} ({year}) {{tvdb-{tvdb_id}}} → Breaking Bad (2008) {tvdb-81189}

filesystem.season_dir_template

string

default:"\"Season {season:02d}\""

Template for season subdirectory names.Available variables: season (integer, supports Python format specifiers), show (object with [title], [year], [tvdb_id], [imdb_id])Examples:

Season {season:02d} → Season 01
S{season:02d} → S01
{show[title]} - Season {season} → Breaking Bad - Season 1

filesystem.episode_file_template

string

default:"\"{show[title]} - s{season:02d}e{episode:02d}\""

Template for episode file names, without extension. For multi-episode files, Riven automatically formats the episode range using the same zero-padding format (e.g., e01-05).Available variables: title (episode title), season, episode, show (object with [title], [year], [tvdb_id], [imdb_id]), resolution, codec, hdr, audio, quality, remux, proper, repack, extended, directors_cut, editionExamples:

{show[title]} - s{season:02d}e{episode:02d} → Breaking Bad - s01e01.mkv
S{season:02d}E{episode:02d} - {title} → S01E01 - Pilot.mkv

Template strings are validated on startup using a safe formatter. An invalid template (e.g., referencing a variable that does not exist or a malformed format specifier) will cause Riven to reject the settings with a validation error.

Library profiles

Library profiles let you organize the VFS into separate sub-paths based on item metadata. Each profile defines a library_path prefix and a set of filter rules. When Riven mounts an item, it checks every enabled profile’s filter rules; the item appears under every profile whose filters match it. This is useful for creating separate Plex/Jellyfin/Emby libraries for anime, kids content, or any other category — without duplicating actual storage. Profile key rules:

Keys must be lowercase alphanumeric with underscores only (e.g., anime, kids_content).
The key default is reserved and cannot be used.
The paths /movies and /shows under the mount are reserved for base directories.
Duplicate library_path values among enabled profiles are not allowed.

filesystem.library_profiles

object

default:"(see below)"

A dictionary of profile key → LibraryProfile objects. By default, Riven ships with an anime profile (enabled) and an example_kids profile (disabled as an example).Each LibraryProfile has:

name — Human-readable label (e.g., "Anime").
library_path — VFS path prefix for this profile (e.g., "/anime"). Must start with /, contain only alphanumeric characters, dashes, underscores, and slashes, and not be /default, /movies, or /shows.
enabled — Whether this profile is active.
filter_rules — A LibraryProfileFilterRules object (see below).

Filter rules

Filter rules are metadata-only predicates evaluated against each item’s fetched metadata. All rules in a profile must match for an item to appear under that profile’s path.

filter_rules.content_types

list[string] | null

default:"null"

Media types to include. Accepted values: "movie", "show". Set to null or omit to match all types.

filter_rules.genres

list[string] | null

default:"null"

Genres to include or exclude. Prefix a genre with ! to exclude it. Items are matched if they have any of the included genres and none of the excluded genres. Set to null or omit for no genre filter.Examples:

["animation", "family"] — include items that are animation or family.
["action", "!horror"] — include action items but exclude horror.

filter_rules.min_year

integer | null

default:"null"

Minimum release year (≥ 1900). Items released before this year are excluded. Set to null for no lower bound.

filter_rules.max_year

integer | null

default:"null"

Maximum release year. Items released after this year are excluded. Set to null for no upper bound.

filter_rules.is_anime

boolean | null

default:"null"

Filter by the anime flag on the item’s metadata. true = anime only, false = non-anime only, null = no filter.

filter_rules.networks

list[string] | null

default:"null"

TV networks to include or exclude. Use ! prefix to exclude. Applies to shows only.

filter_rules.countries

list[string] | null

default:"null"

Countries of origin to include or exclude (ISO 3166-1 alpha-2 codes, e.g. "US", "GB"). Use ! prefix to exclude.

filter_rules.languages

list[string] | null

default:"null"

Languages to include or exclude (ISO 639-1 codes, e.g. "en", "ja"). Use ! prefix to exclude.

filter_rules.min_rating

float | null

default:"null"

Minimum rating on a 0–10 scale. Items with a lower rating are excluded. Set to null for no minimum.

filter_rules.max_rating

float | null

default:"null"

Maximum rating on a 0–10 scale. Set to null for no maximum.

filter_rules.content_ratings

list[string] | null

default:"null"

Content ratings to include or exclude. Use ! prefix to exclude. Common values: G, PG, PG-13, R, NC-17, TV-Y, TV-Y7, TV-G, TV-PG, TV-14, TV-MA.

Default anime profile

Riven ships with this profile enabled out of the box:

{
  "filesystem": {
    "library_profiles": {
      "anime": {
        "name": "Anime",
        "library_path": "/anime",
        "enabled": true,
        "filter_rules": {
          "is_anime": true
        }
      }
    }
  }
}

All items flagged as anime in their metadata will appear under <mount_path>/anime/ in addition to the default path, allowing you to point Plex or Jellyfin at that sub-path for a dedicated anime library.

Example: kids and family profile

The following profile separates family-friendly movies and shows into a /kids sub-path:

{
  "filesystem": {
    "library_profiles": {
      "kids_content": {
        "name": "Kids & Family Content",
        "library_path": "/kids",
        "enabled": true,
        "filter_rules": {
          "content_types": ["movie", "show"],
          "genres": ["animation", "family", "!horror"],
          "content_ratings": ["G", "PG", "TV-Y", "TV-Y7", "TV-G", "TV-PG"],
          "max_rating": 7.5
        }
      }
    }
  }
}

This matches any movie or show that is in the animation or family genre (but not horror), has a content rating of G, PG, TV-Y, TV-Y7, TV-G, or TV-PG, and has a rating of 7.5 or below.

Items can appear in multiple library profiles simultaneously. A family anime film would show up under both the /anime and /kids paths if both profiles are enabled and their filters match.

Getting Started

Configuration

Core Concepts

Guides

Configure RivenVFS Filesystem and Library Profiles

Mount path

Cache settings

Naming templates

Movie templates

Show templates

Library profiles

Filter rules

Default anime profile

Example: kids and family profile

Build docs developers (and LLMs) love

Getting Started

Configuration

Core Concepts

Guides

Documentation Index

​Mount path

​Cache settings

​Naming templates

​Movie templates

​Show templates

​Library profiles

​Filter rules

​Default anime profile

​Example: kids and family profile

Build docs developers (and LLMs) love

Mount path

Cache settings

Naming templates

Movie templates

Show templates

Library profiles

Filter rules

Default anime profile

Example: kids and family profile