Riven has been rewritten more than once. Before installing anything, it is worth spending two minutes understanding which edition is which, because the configuration format, architecture, and feature set differ substantially between them. The short answer for anyone starting fresh is Riven TS — the TypeScript rewrite and the only version receiving new features.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.
Version overview
| Version | Status | Language | Repository |
|---|---|---|---|
| Riven TS | Active development | TypeScript | rivenmedia/riven-ts |
| Riven v1 | Maintenance only | Python | formerly rivenmedia/riven |
| Riven v0 | Deprecated | Python | — |
| Riven RS | Community project | Rust | olivertgwalton/riven-rs |
Riven TS (Recommended)
Riven TS is a complete rewrite of the project in TypeScript. It is the official version, and the only one that receives new features and bug fixes. All documentation on this site covers Riven TS unless stated otherwise.Plugin architecture
A first-class plugin SDK lets you build and ship custom integrations without forking the core. TMDB, TVDB, Plex, Jellyfin, StremThru, and others are all implemented as plugins.
GraphQL API
Apollo Server with
type-graphql exposes a typed, self-documenting GraphQL schema. All UI and automation tooling talks to a single endpoint on port 3000.XState state machines
Media item lifecycles — from discovery through scraping, validation, and library inclusion — are modelled as explicit state machines that survive restarts gracefully.
BullMQ job queues
Redis-backed queues decouple work into retryable, observable jobs. The queue dashboard (Bull Board) is available as an optional sidecar service.
FUSE virtual file system
Riven mounts a virtual file system via FUSE. Your media server sees a real directory tree without any disk-copying or symlink fragility.
MikroORM + PostgreSQL
All state is stored in PostgreSQL 17, managed through MikroORM. Migrations run automatically on startup.
Riven v1
Riven v1 was the previous stable version, written in Python. It followed a monolithic design with a REST API and used symlinks or rclone instead of FUSE. The configuration format is asettings.json file rather than environment variables.
Key differences from Riven TS:
- Monolithic Python application — no plugin system
- REST API instead of GraphQL
settings.jsonconfiguration rather thanRIVEN_SETTING__*environment variables- Symlinks or rclone for media presentation rather than a FUSE VFS
Riven v0
Riven v0 is the original implementation. It relied on symlinks and had architectural limitations that motivated the v1 rewrite.Riven RS
Riven RS is a community implementation written in Rust by Oli. It is an independent project with its own design decisions, architecture, and configuration format — not a fork of Riven TS. Key points:- A separate community project, not the official Riven
- Written in Rust for performance
- Has its own roadmap and is maintained independently
- Does not share the plugin SDK or GraphQL API with Riven TS
Which should I use?
I'm a new user starting from scratch
I'm a new user starting from scratch
Use Riven TS. It is the officially maintained version with active development, a plugin SDK, and full documentation.
I'm currently running Riven v1
I'm currently running Riven v1
Plan a migration to Riven TS when you have a maintenance window. Riven v1 is in maintenance mode — it will not gain new features and support will wind down over time.
I'm currently running Riven v0
I'm currently running Riven v0
Migrate to Riven TS as soon as possible. Riven v0 receives no fixes of any kind.
I prefer a Rust runtime
I prefer a Rust runtime
Check out Riven RS (community project). Note that it has a different configuration format and community, and is not supported by this documentation.