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.

Docker is the recommended way to run Riven TS for most users. Running from source makes sense when FUSE-in-Docker is awkward on your host, when you want to track the main branch very closely, or when you simply prefer a direct process rather than a container. Everything here assumes a Linux host — macOS and Windows are not supported.
If you want to contribute code rather than deploy, see CONTRIBUTING.md instead. It covers codegen, running tests, and the local development service stack.

​
Prerequisites

  • Node.js 24.15+ — check with node --version
  • pnpm 11.5+ — check with pnpm --version
  • PostgreSQL 17 reachable from the host
  • Redis 8 reachable from the host
  • FUSE userspace libraries (libfuse.so.2 must be present on the host)

​
Setup

1

Install FUSE and allow non-root mounts

Install the FUSE userspace libraries for your distribution:
sudo apt install fuse3
Then enable user_allow_other in /etc/fuse.conf. Without it, the VFS mounts successfully but no other process on the system — including your media server — can read it:
sudo sed -i 's/^#\s*user_allow_other/user_allow_other/' /etc/fuse.conf
Verify the line is uncommented:
grep user_allow_other /etc/fuse.conf
# user_allow_other
2

Create the mount point

Create /mnt/riven and give your user ownership so Riven can mount the VFS without sudo:
sudo mkdir -p /mnt/riven
sudo chown -R "$(id -u):$(id -g)" /mnt/riven
3

Clone and build

Clone the repository, install all workspace dependencies, then build the @repo/riven package (Turborepo resolves internal package dependencies automatically):
git clone https://github.com/rivenmedia/riven-ts.git
cd riven-ts
pnpm install
pnpm turbo build --filter=@repo/riven
The build compiles TypeScript to apps/riven/dist/ and bundles the sandboxed worker scripts.
4

Configure

Riven reads its configuration from apps/riven/.env.riven. Copy the bundled example as a starting point:
cp apps/riven/.env.riven.example apps/riven/.env.riven
Open the file and set at minimum your database URL, Redis URL, mount path, and TMDB API key:
apps/riven/.env.riven
# ── Core ──────────────────────────────────────────────────────────────────

## PostgreSQL connection URL
RIVEN_SETTING__databaseUrl="postgresql+psycopg2://riven:CHANGEME@localhost:5432/riven"

## Redis connection URL
RIVEN_SETTING__redisUrl="redis://127.0.0.1:6379"

## VFS mount path (created in Step 2)
RIVEN_SETTING__vfsMountPath="/mnt/riven"

## Application log level: debug | info | warn | error
RIVEN_SETTING__logLevel="info"

## Plugins to enable (tmdb and tvdb are always active)
RIVEN_SETTING__enabledPlugins=["seerr","stremthru","torrentio","plex"]

# ── Metadata ──────────────────────────────────────────────────────────────

RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey="your-tmdb-api-key"

# ── Debrid (via StremThru) ────────────────────────────────────────────────

RIVEN_PLUGIN_SETTING__REPO_PLUGIN_STREMTHRU__realdebridApiKey="your-rd-key"

# ── Content source ────────────────────────────────────────────────────────

RIVEN_PLUGIN_SETTING__REPO_PLUGIN_SEERR__url="http://localhost:5055"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_SEERR__apiKey="your-seerr-key"

# ── Media server ──────────────────────────────────────────────────────────

RIVEN_PLUGIN_SETTING__REPO_PLUGIN_PLEX__plexToken="your-plex-token"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_PLEX__plexServerUrl="http://localhost:32400"
Unlike the Docker setup you do not need to set RIVEN_SETTING__gqlHost. The default of localhost is correct for a direct host process. Set it to 0.0.0.0 only if other machines need to reach the GraphQL API.
See Configuration for every available core setting, and Plugins for per-plugin options.
5

Run Riven

Start the process from the repository root:
pnpm --filter @repo/riven start
Riven runs database migrations, connects to Redis, registers plugins, mounts the VFS at /mnt/riven, and serves the GraphQL API on port 3000. Logs are written to apps/riven/logs/.Confirm the API is responding:
curl -X POST http://localhost:3000 \
  -H 'content-type: application/json' \
  -d '{"query":"{ __typename }"}'
# {"data":{"__typename":"Query"}}

​
Running as a systemd service

To keep Riven running across reboots, create a systemd unit. The ExecStartPre line re-applies shared propagation to the mount point so the VFS remains visible to other processes after a reboot:
/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
Enable and start it: 
sudo systemctl daemon-reload
sudo systemctl enable --now riven.service
sudo journalctl -u riven.service -f
The User=riven directive assumes you have created a dedicated system user and that /opt/riven-ts is owned by that user. Adjust the User and WorkingDirectory values to match your actual setup.

​
Updating

Pull the latest commits, reinstall any changed dependencies, and rebuild: 
git pull
pnpm install
pnpm turbo build --filter=@repo/riven
Database migrations run automatically on the next startup — no manual migration step is required.

​
What’s next?

Configure plugins

Set up content sources, your debrid provider, and media server integrations.

Production deployment

Reverse proxy, TLS termination, and monitoring recommendations.

Troubleshooting

Solutions for common FUSE, permission, and connectivity issues.

Docker Compose quickstart

Prefer containers? Follow the Docker Compose guide instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us