Riven is a self-hosted media automation framework. It connects your content wishlist (Seerr, MDBList, Listrr) to your media server (Plex, Jellyfin) by orchestrating every step of the pipeline — metadata lookup, torrent scraping, debrid downloading, and virtual filesystem mounting — through a modular, plugin-based architecture.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.
Quickstart
Install and run Riven with Docker Compose in minutes
From Source
Build and run Riven directly on the host with Node.js
Architecture
Understand the state machine pipeline and core components
Plugin SDK
Build your own plugins to extend Riven
Plugins
Browse available plugins and configure them
Ranking
Configure how torrents are scored and selected
How Riven works
Riven runs a continuous pipeline driven by typed events and XState state machines:Content Discovery
Plugins like Seerr, MDBList, or Listrr submit item requests to Riven. Each request carries an IMDb ID, TMDB ID, or TVDB ID.
Metadata Indexing
The TVDB and TMDB plugins fetch full metadata — episode lists, season counts, air dates — and store it in PostgreSQL via MikroORM entities.
Torrent Scraping
Scraper plugins (Torrentio, Comet) search for available torrents. Results are parsed and ranked by the configurable torrent ranking engine.
Debrid Downloading
The top-ranked torrent is sent to StremThru, which caches it on your debrid provider (Real-Debrid, AllDebrid, TorBox, etc.) and returns a direct stream link.
VFS Mount
A FUSE virtual filesystem mounts the debrid content at
/mnt/riven. No symlinks, no file copies — the files appear locally.Key features
Plugin Architecture
Every integration is a plugin — metadata providers, scrapers, downloaders, content sources, and media servers. Extend Riven with the Plugin SDK.
FUSE Virtual Filesystem
Clean FUSE mount with no symlinks or file copies. Files appear local to your media server while living on your debrid provider.
GraphQL API
Apollo Server + type-graphql API for querying your library, managing item requests, and interacting with the VFS.
XState State Machines
The entire processing pipeline is modelled as XState v5 state machines — reliable, inspectable, and recoverable.
BullMQ Job Queues
Redis-backed job queues with per-plugin rate limiting, exponential backoff, deduplication, and flow orchestration.
Torrent Ranking Engine
Score torrents by quality, codec, HDR format, audio format, and custom rules. Ships with a sensible default preset.
Riven versions
Riven has had multiple implementations. Riven TS is the current, actively developed version and the one you should use.| Version | Status | Language |
|---|---|---|
| Riven TS | Active development | TypeScript |
| Riven v1 | Maintenance only | Python |
| Riven v0 | Deprecated | Python |
| Riven RS | Community project | Rust |