Riven is a media automation system that uses a virtual file system and debrid services to find, organize, and stream your media. It integrates with Plex, Jellyfin, and many other services.

Riven-TS is the official TypeScript rewrite of Riven, featuring a modern plugin architecture, GraphQL API, and extensible design. It is the actively developed version going forward.

How do I get started with Riven?

Deploy Riven with Docker using our compose generator or follow the documentation at https://riven.tv/docs.

Running from Source

Docker is the recommended way to run Riven. Running from source is worth it if you need to run on a host where FUSE-in-Docker is awkward, or you want to track main closely.

Looking to contribute rather than deploy? See CONTRIBUTING.md instead — it covers codegen, tests, and the local service stack.

Prerequisites

Node.js 24.15+ and pnpm 11.5+
PostgreSQL 17 and Redis 8, reachable from the host
FUSE libraries — Riven needs libfuse.so.2 present

Install FUSE and allow non-root mounts

# Debian / Ubuntu
sudo apt install fuse3

# Arch
sudo pacman -S fuse fuse3

Then uncomment user_allow_other in /etc/fuse.conf. Without it the VFS mounts but nothing else on the system can read it:

sudo sed -i 's/^#\s*user_allow_other/user_allow_other/' /etc/fuse.conf

Create the mount point

sudo mkdir -p /mnt/riven
sudo chown -R "$(id -u):$(id -g)" /mnt/riven

Build

git clone https://github.com/rivenmedia/riven-ts.git
cd riven-ts
pnpm install
pnpm turbo build --filter=@repo/riven

Configure

Riven reads apps/riven/.env.riven. Start from the bundled example:

cp apps/riven/.env.riven.example apps/riven/.env.riven

At minimum, set your database, Redis, mount path, and TMDB key:

apps/riven/.env.riven

RIVEN_SETTING__databaseUrl="postgres+psycopg2://riven:CHANGEME@localhost:5432/riven"
RIVEN_SETTING__redisUrl="redis://127.0.0.1:6379"
RIVEN_SETTING__vfsMountPath="/mnt/riven"
RIVEN_SETTING__enabledPlugins=["seerr","stremthru","torrentio","plex"]
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey="your-tmdb-api-key"

Unlike the Docker setup you do not need gqlHost — the default of localhost is correct when nothing has to reach Riven across a network boundary. Set it to 0.0.0.0 only if other machines need the API.

The full list of settings is on the Configuration page.

Run

pnpm --filter @repo/riven start

Logs are written to apps/riven/logs and the GraphQL API listens on port 3000.

Running as a service

To keep Riven running across reboots, wrap the start command in a systemd unit. Note the --make-rshared mount, which is what lets other processes see the VFS:

/etc/systemd/system/riven.service

[Unit]
Description=Riven
After=network-online.target postgresql.service redis.service

[Service]
Type=simple
User=riven
WorkingDirectory=/opt/riven-ts
ExecStartPre=/usr/bin/mount --make-rshared /mnt/riven
ExecStart=/usr/bin/pnpm --filter @repo/riven start
Restart=on-failure

[Install]
WantedBy=multi-user.target

Updating

git pull
pnpm install
pnpm turbo build --filter=@repo/riven

Database migrations run automatically on the next start.

Running from Source

On this page