selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

GitHub
jellysweep logo

Self-host jellysweep

v0.16.1

Smart cleanup tool for Jellyfin media server

BetaOpen SourceGPL-3.0
GitHub
Install
Updated15 hours ago
LanguageGo
Setup difficultyAdvanced
MobilePWA
Stars
260
Port
3002 (Web interface)
Requires
Jellyfin, Jellyseerr
Docker
ghcr.io/jon4hz/jellysweep
Install with Docker Compose
Dashboard Overview showing media items scheduled for deletion with filtering and searchStatistics Dashboard with visual analytics of daily and cumulative storage cleanupAdmin Panel - Keep Requests queue for reviewing user keep requestsAdmin Panel - Keep or Sweep interface for final keep/delete decisionsScheduler Panel for controlling tasks and viewing cache statistics

What is jellysweep?

Jellysweep is a self-hosted media cleanup tool for Jellyfin servers. It connects to Jellyfin, Sonarr, Radarr, Jellyseerr, and optionally Jellystat or Streamystats to analyze viewing statistics and user requests. Based on configurable filters (content age, last stream date, size, favorites, Tunarr usage, and exclusion tags), it marks eligible media for deletion by tagging items in Sonarr/Radarr. Users can request to keep specific items through a web interface, and admins review these requests. After a configurable grace period — which shortens automatically when disk usage crosses defined thresholds — the tagged media is deleted. The tool offers three cleanup modes for TV series (all, keep_episodes, keep_seasons), creates Jellyfin "Leaving" collections for scheduled deletions, and provides a Progressive Web App interface with OIDC or Jellyfin authentication. It runs via Docker Compose, uses SQLite or PostgreSQL for its own database, and can cache with Valkey/Redis.

Should you self-host jellysweep?

jellysweep scores 45/100 on selfhost.directory (how scoring works) and ranks #98 of 142 in Media Management. It has 260 GitHub stars.

It shipped 6 stable releases in the past year. The latest, v0.16.1, came out on 15 September 2026. New versions land roughly every 2 months.

Setup is advanced: plan for several services and some ongoing maintenance. An official Docker image is available. It is GPL-3.0-licensed and written mostly in Go.

Its closest alternative on selfhost.directory is Sonarr (81/100, 17 475 stars). It scores higher overall, so compare the two before you pick. See jellysweep vs Sonarr side by side.

Features

  • Content filters
  • Disk Usage Monitoring
  • Dry Run Mode
  • Flexible Cleanup Modes
  • Grace Period with Disk-Adaptive Reduction
  • Leaving Collections
  • Notifications
  • OIDC/SSO Authentication
  • Progressive Web App
  • Smart Analytics
  • Tag-Based Control
  • User Keep Requests
  • Web Interface

jellysweep README

How to install jellysweep

Install jellysweep with Docker Compose

Jellyfin, Sonarr/Radarr, Jellyseerr, Jellystat/Streamystats
Environment variables
JELLYSWEEP_CACHE_TYPE=redis, JELLYSWEEP_CACHE_REDIS_URL=valkey:6379

services: jellysweep: image: ghcr.io/jon4hz/jellysweep:latest container_name: jellysweep restart: unless-stopped ports: - "3002:3002" volumes: - ./config.yml:/app/config.yml:ro - ./data:/app/data environment: - JELLYSWEEP_DRY_RUN=false - JELLYSWEEP_LISTEN=0.0.0.0:3002

Start the service

docker compose up -d

View logs

docker compose logs -f jellysweep

Reset all tags (cleanup command)

docker compose exec jellysweep ./jellysweep reset

Configuration via config.yml file or environment variables

How to configure jellysweep

  • JELLYSWEEP_API_KEYAPI key for the Jellysweep server (used by the Jellyfin plugin)

    API key for the Jellysweep server (used by the Jellyfin plugin)

  • JELLYSWEEP_AUTH_JELLYFIN_ENABLEDtrueEnable Jellyfin authentication

    Enable Jellyfin authentication

    values: true, false

  • JELLYSWEEP_AUTH_OIDC_ADMIN_GROUPGroup with admin privileges

    Group with admin privileges

  • JELLYSWEEP_AUTH_OIDC_AUTO_APPROVE_GROUPGroup with auto-approval permission for keep requests

    Group with auto-approval permission for keep requests

  • JELLYSWEEP_AUTH_OIDC_CLIENT_IDOIDC client ID

    OIDC client ID

  • JELLYSWEEP_AUTH_OIDC_CLIENT_SECRETOIDC client secret

    OIDC client secret

  • JELLYSWEEP_AUTH_OIDC_ENABLEDfalseEnable OIDC/SSO authentication

    Enable OIDC/SSO authentication

    values: true, false

  • JELLYSWEEP_AUTH_OIDC_ISSUEROIDC issuer URL

    OIDC issuer URL

  • JELLYSWEEP_AUTH_OIDC_NAMEOIDCDisplay name on the login page

    Display name on the login page

  • JELLYSWEEP_AUTH_OIDC_REDIRECT_URLOIDC redirect URL

    OIDC redirect URL

  • JELLYSWEEP_AUTH_OIDC_USE_PKCEfalseEnable PKCE for enhanced security

    Enable PKCE for enhanced security

    values: true, false

  • JELLYSWEEP_CACHE_REDIS_URLlocalhost:6379Redis server URL (when using redis cache)

    Redis server URL (when using redis cache)

  • JELLYSWEEP_CACHE_TYPEmemoryCache type: memory or redis

    Cache type: memory or redis

    values: memory, redis

  • JELLYSWEEP_CLEANUP_MODEallCleanup mode: all, keep_episodes, or keep_seasons

    Cleanup mode: all, keep_episodes, or keep_seasons

    values: all, keep_episodes, keep_seasons

  • JELLYSWEEP_CLEANUP_SCHEDULE0 */12 * * *Cron schedule for cleanup runs

    Cron schedule for cleanup runs

  • JELLYSWEEP_DATABASE_HOSTPostgreSQL server host

    PostgreSQL server host

  • JELLYSWEEP_DATABASE_NAMEPostgreSQL database name

    PostgreSQL database name

  • JELLYSWEEP_DATABASE_PASSWORDPostgreSQL password

    PostgreSQL password

  • JELLYSWEEP_DATABASE_PATH./data/jellysweep.dbPath to the database file (for SQLite)

    Path to the database file (for SQLite)

  • JELLYSWEEP_DATABASE_PORT5432PostgreSQL server port

    PostgreSQL server port

  • JELLYSWEEP_DATABASE_SSL_MODEdisablePostgreSQL SSL mode

    PostgreSQL SSL mode

  • JELLYSWEEP_DATABASE_TYPEsqliteDatabase backend: sqlite or postgres

    Database backend: sqlite or postgres

    values: sqlite, postgres

  • JELLYSWEEP_DATABASE_USERPostgreSQL user

    PostgreSQL user

  • JELLYSWEEP_DRY_RUNtrueRun in dry-run mode (no actual deletions)

    Run in dry-run mode (no actual deletions)

    values: true, false

  • JELLYSWEEP_EMAIL_ENABLEDfalseEnable email notifications

    Enable email notifications

    values: true, false

  • JELLYSWEEP_EMAIL_FROM_EMAILFrom email address

    From email address

  • JELLYSWEEP_EMAIL_FROM_NAMEJellysweepFrom name for emails

    From name for emails

  • JELLYSWEEP_EMAIL_INSECURE_SKIP_VERIFYfalseSkip TLS certificate verification

    Skip TLS certificate verification

    values: true, false

  • JELLYSWEEP_EMAIL_PASSWORDSMTP password

    SMTP password

  • JELLYSWEEP_EMAIL_SMTP_HOSTSMTP server host

    SMTP server host

  • JELLYSWEEP_EMAIL_SMTP_PORT587SMTP server port

    SMTP server port

  • JELLYSWEEP_EMAIL_USERNAMESMTP username

    SMTP username

  • JELLYSWEEP_EMAIL_USE_SSLfalseUse SSL for SMTP connection

    Use SSL for SMTP connection

    values: true, false

  • JELLYSWEEP_EMAIL_USE_TLStrueUse TLS for SMTP connection

    Use TLS for SMTP connection

    values: true, false

  • JELLYSWEEP_GRAVATAR_DEFAULT_IMAGErobohashDefault image if no Gravatar found

    Default image if no Gravatar found

    values: 404, mp, identicon, monsterid, wavatar, retro, robohash, blank

  • JELLYSWEEP_GRAVATAR_ENABLEDfalseEnable Gravatar profile pictures

    Enable Gravatar profile pictures

    values: true, false

  • JELLYSWEEP_GRAVATAR_RATINGgMaximum rating for images

    Maximum rating for images

    values: g, pg, r, x

  • JELLYSWEEP_GRAVATAR_SIZE80Image size in pixels (1-2048)

    Image size in pixels (1-2048)

  • JELLYSWEEP_JELLYFIN_API_KEYJellyfin API key

    Jellyfin API key

  • JELLYSWEEP_JELLYFIN_URLJellyfin server URL

    Jellyfin server URL

  • JELLYSWEEP_JELLYSEERR_API_KEYJellyseerr API key

    Jellyseerr API key

  • JELLYSWEEP_JELLYSEERR_URLJellyseerr server URL

    Jellyseerr server URL

  • JELLYSWEEP_JELLYSTAT_API_KEYJellystat API key

    Jellystat API key

  • JELLYSWEEP_JELLYSTAT_URLJellystat server URL

    Jellystat server URL

  • JELLYSWEEP_KEEP_COUNT1Number of episodes/seasons to keep (when using keep_episodes or keep_seasons mode)

    Number of episodes/seasons to keep (when using keep_episodes or keep_seasons mode)

  • JELLYSWEEP_LEAVING_COLLECTIONS_ENABLEDfalseCreate collections for media scheduled for deletion

    Create collections for media scheduled for deletion

    values: true, false

  • JELLYSWEEP_LEAVING_COLLECTIONS_MOVIE_NAMELeaving MoviesName of the leaving movies collection

    Name of the leaving movies collection

  • JELLYSWEEP_LEAVING_COLLECTIONS_TV_NAMELeaving TV ShowsName of the leaving TV shows collection

    Name of the leaving TV shows collection

  • JELLYSWEEP_LISTEN0.0.0.0:3002Address and port for the web interface

    Address and port for the web interface

  • JELLYSWEEP_LOG_LEVELinfoLog verbosity: debug, info, warn, or error

    Log verbosity: debug, info, warn, or error

    values: debug, info, warn, error

  • JELLYSWEEP_NTFY_ENABLEDfalseEnable ntfy notifications

    Enable ntfy notifications

    values: true, false

  • JELLYSWEEP_NTFY_PASSWORDNtfy password for authentication

    Ntfy password for authentication

  • JELLYSWEEP_NTFY_SERVER_URLhttps://ntfy.shNtfy server URL

    Ntfy server URL

  • JELLYSWEEP_NTFY_TOKENNtfy token for authentication

    Ntfy token for authentication

  • JELLYSWEEP_NTFY_TOPICNtfy topic to publish to

    Ntfy topic to publish to

  • JELLYSWEEP_NTFY_USERNAMENtfy username for authentication

    Ntfy username for authentication

  • JELLYSWEEP_RADARR_API_KEYRadarr API key

    Radarr API key

  • JELLYSWEEP_RADARR_URLRadarr server URL

    Radarr server URL

  • JELLYSWEEP_SECURE_COOKIEStrueSet the Secure flag on session cookies (disable only for local development)

    Set the Secure flag on session cookies (disable only for local development)

    values: true, false

  • JELLYSWEEP_SERVER_URLhttp://localhost:3002Base URL of the Jellysweep server

    Base URL of the Jellysweep server

  • JELLYSWEEP_SESSION_KEYRandom string for session encryption (openssl rand -base64 32)

    Random string for session encryption (openssl rand -base64 32)

  • JELLYSWEEP_SESSION_MAX_AGE172800Session maximum age in seconds (48 hours)

    Session maximum age in seconds (48 hours)

  • JELLYSWEEP_SONARR_API_KEYSonarr API key

    Sonarr API key

  • JELLYSWEEP_SONARR_URLSonarr server URL

    Sonarr server URL

  • JELLYSWEEP_STREAMYSTATS_SERVER_IDStreamystats Jellyfin server ID

    Streamystats Jellyfin server ID

  • JELLYSWEEP_STREAMYSTATS_URLStreamystats server URL

    Streamystats server URL

  • JELLYSWEEP_TRUSTED_PROXIESComma-separated list of trusted proxy IPs/CIDRs

    Comma-separated list of trusted proxy IPs/CIDRs

  • JELLYSWEEP_TUNARR_URLTunarr server URL

    Tunarr server URL

  • JELLYSWEEP_WEBPUSH_ENABLEDfalseEnable web push notifications

    Enable web push notifications

    values: true, false

  • JELLYSWEEP_WEBPUSH_PRIVATE_KEYVAPID private key

    VAPID private key

  • JELLYSWEEP_WEBPUSH_PUBLIC_KEYVAPID public key

    VAPID public key

  • JELLYSWEEP_WEBPUSH_VAPID_EMAILContact email for VAPID keys

    Contact email for VAPID keys

jellysweep releases & version history

Even more releases RSS

More in Media Server

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…