Velvarr – The discovery and request app for adult media

---

Velvarr is a free and open source discovery and request app for adult media. Browse movies, scenes, performers, and studios from TPDB and StashDB, request them into Whisparr (Eros) with administrator approval, and watch in Jellyfin through a credential-free link.

Features

• Provider-backed catalogs — movies (TPDB), scenes (TPDB + StashDB), performers (with the biography facts the provider publishes), and studios, each with the filters and sort orders that provider actually supports
• One Browse surface — TPDB movies and StashDB scenes in a single grid with title search, tag include/exclude, studio, performer, year, and date filters; every constraint rides in the URL
• Global search across both providers, plus unified Studios and Genres rails; results are never merged across providers and cross-provider identity comes only from links the providers publish — never name matching
• Durable requests with administrator or moderator approval and an optional per-account auto-approve grant; the Requests list filters by media type and status and sorts by most recent or last modified
• Crash-safe acquisition worker — every attempt is persisted before any network call and reconciled by exact identity after a restart; never a lost or duplicated add
• Per-user Jellyfin availability and credential-free watch links
• Performer follows — Merge follows the current performer if needed and pairs the selected, already-followed entry on the other provider. Failed merges leave follows unchanged.
• Personal preferences — per-account hidden tags and Discover shelf ordering
• Similar titles on movies and scenes (shared published tags) and Often appears with on performers (co-appearance)
• Update notice — the sidebar shows a chip linking to a newer GitHub release; the server asks api.github.com at most once an hour (VELVARR_UPDATE_CHECK=0 disables it)
• Optional Discord notifier posting to a private webhook, identity-only by default
• Optional AI-assisted matching via TypeSafe — a near-miss Jellyfin title is flagged "ambiguous — administrator review", never auto-available; without a key, matching is exact

Getting started

Docker (recommended):

docker compose up -d   # pulls ghcr.io/skare69/velvarr

To upgrade, bump the image tag in compose.yaml, then docker compose pull && docker compose up -d.

From source (Node 24.21+, Bun 1.3.14+):

bun install
bun run setup   # writes .env.local with fresh secrets; never overwrites existing credentials
bun run dev     # http://127.0.0.1:6699

Configuration

bun run setup generates the required secrets. Back up VELVARR_SECRET_KEY: losing it makes the stored database and every backup unreadable.

Variable	Required	Meaning
VELVARR_SECRET_KEY	yes	64 hex chars; decrypts credentials stored in the database. Restores need the key from backup time.
VELVARR_SETUP_SECRET	until bootstrap	≥ 32 characters; gates the one-time owner setup.
VELVARR_ORIGIN	no	Pin the public origin (e.g. behind a reverse proxy); mutations from other origins are refused. Unset, CSRF safety comes from the HttpOnly + SameSite=Strict session cookie alone.
VELVARR_DATA_DIR	no	Data directory; default ./data, /data in the container.
VELVARR_ALLOW_HTTP	no	1 allows plain HTTP for private/Docker-network addresses on the LAN.
VELVARR_DISCORD_WEBHOOK_URL	no	Private Discord webhook for notifications; https only.
VELVARR_DISCORD_DETAIL	no	1 includes titles in notifications; off by default, messages stay identity-only.
TYPESAFE_API_KEY	no	Enables AI-assisted Jellyfin matching; a key saved in Settings → Metadata providers takes precedence.
VELVARR_UPDATE_CHECK	no	0 disables the release check. By default the server asks GitHub (api.github.com) for the latest release at most once an hour — ten minutes after a failure — to show the update chip.

Backup and recovery

bun run backup /backups/velvarr.sqlite   # consistent online snapshot; refuses to overwrite

To restore: start from a fresh data directory, copy the snapshot in as velvarr.sqlite, and start with the same VELVARR_SECRET_KEY as when the backup was taken. The key is never stored in the backup.

Repository layout

Branch / remote	Contents
main	Clean standalone product; no inherited Seerr application
legacy/seerr-whisparr	Seerr integration snapshot; reference only
upstream	seerr-team/seerr; not a merge source

License

Licensed under the MIT License.