Caution

• 23-04-2026: Right now working on stabilizing build whenever dependencies upgrades happen...
• 13-06-2026: Latest image available on docker hub
• 15-06-2026: relase 1.3.4 was broken sorry

JellyGrail

One compatibility layer to rule them all.
Enhanced Jellyfin Docker image that bridges local, cloud and Debrid media sources to players like Kodi, Jellyfin, and Plex through unified virtual filesystem (JGFS) and easy synchronisation.
WARNING: This project is still experimental/ALPHA !

Prerequisites • Install • Kodi add-on • Usage • Troubleshooting • Performance

---

• Merging multiple media sources into one virtualized filesystem (JGFS) - https://github.com/philamp/bindfs_jelly :
  • On-the-fly unraring - https://github.com/hasse69/rar2fs.
  • Virtual moving/renaming.
  • Writing new files goes into local fallback storage.
  • Deleting virtual files deletes underlying actual files.
  • Native Debrid integration + rclone optimization (with iso/rar structure cache) - https://github.com/philamp/rclone_jelly.
    • Supports Real-Debrid, Premiumize and Torbox 🆕.
  • ffprobe wrapper to avoid redundant ffprobe requests (except with Plex).
  • Keep movie extras and subtitles.
  • Comprehensive folders structure and naming pattern to maximize compatibility and readability.
  • Merging similarly named medias in same folder (weak point as sometimes it can merge different medias, would be better fetching metadata from *arrs).
• Multiple media libraries sync:
  • Jellyfin included with zero-click setup.
  • Kodi (v20 and v21) native sync with multiple Kodi players support :
    • Based on MariaDB + Nginx WebDAV server (with local storage fallback).
    • Kodi add-on with exclusive functionalities - https://github.com/philamp/grail_kodi.
    • Seamless local server detection and setup.
    • Update triggering + metadata synced from Jellyfin.
    • Auto-merging of movies variants.
    • Image resampling to reduce Kodi’s memory usage (imgproxy).
  • External Plex support.
  • Basic WebDAV server.

Prerequisites

• ARM64 or x86_64 Linux system 🐧 with Bash shell.
• Docker 🐳 with Buildx (https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository) (optional)
• Git client to clone this repo.
• Bypass media import from your Radarr / Sonarr instances:
  • Uncheck Automatically import completed downloads from download client.
• Local torrent download config:
  • Check Append .!qB extension to incomplete files (example for qBittorrent, but other clients have similar functionality).
• Remote torrent download config:
  • Post Torrent Download Action > Don't download any files to host (example for RealDebrid Client, but other clients have similar functionality).

Caution

• I'm not responsible of any data loss / I'm not responsible of any illegal use / Use at your own risks.
• This solution does not include any torrent indexer search.
• Do not open ports 8385, 16685 and 8389 to the internet.
• ⚠️⚠️ File Deletion in the virtual folder actually deletes corresponding files of underlying file-system(s)⚠️⚠️.
• Jellygrail is still experimental/ALPHA : you should not submit any issues to the XBMC team (Kodi backend emulation disrupts the way Kodi works by modifying the database directly !).

Install

Get

git clone https://github.com/philamp/jellygrail.git 

From now on, this part is optional (image is published on docker Hub):

cd jellygrail/docker
sudo docker buildx build -t philamp/jellygrail --load .

Tip

To update, replace the git clone command by git pull

Configure

Run the config wizard:

cd ..
sudo chmod +x jg-config.sh _MOUNT.SH
./jg-config.sh

Run

Launch your adapted variant of this docker run command, still inside the root folder of the project.

Tip

Beware that by default this working folder will store jellygrail subfolder with config and runtime data such as the rclone ISO/RAR structure cache (0.5%~ of your debrid storage size).

sudo docker run -d \
--security-opt apparmor=unconfined \                          # mandatory for fuse
--cap-add SYS_ADMIN \                                         # mandatory for fuse
--device /dev/fuse \                                          # mandatory for fuse
--device /dev/dri \
--network host \
--memory="8g" \                                                # Increase only if too tight for Jellyfin
--log-driver json-file \
--log-opt max-size=10m \
--log-opt max-file=7 \
-e S6_CMD_WAIT_FOR_SERVICES_MAXTIME=120000 \                    # Avoid s6 failing when services are taking time
-v ${PWD}/jellygrail:/jellygrail \                              # Stores config and runtime data
-v ${PWD}/Video_Library:/Video_Library:rshared \                # The resulting virtualized folder
-v ${PWD}/fallbackdata:/mounts/fallback \                       # Where virtually written files are really stored
-v /path/to/local-video-imports:/mounts/local_import \          # This is where medias will be stored using KEEP add-on feature
-v /path/to/a-local-video-folder:/mounts/local_drive1 \         # the '/mounts/local_' pattern should be used
-v /path/to/another-local-video-folder:/mounts/local_drive2 \   # the '/mounts/local_' pattern should be used
-v /path/remote_yourservice:/mounts/remote_yourservice \        # the '/mounts/remote_' pattern should be used, see below
--restart unless-stopped \
--name jellygrail \
philamp/jellygrail:latest

Warning

• If you're not running an Ubuntu system you will need to run _MOUNT.SH script (with sudo!) to make a two-way bind mount https://forums.docker.com/t/make-mount-point-accesible-from-container-to-host-rshared-not-working/108759.
  • To mount : sudo ./_MOUNT.SH mount.
  • To unmount : sudo ./_MOUNT.SH unmount.

Tip

• run sudo docker logs -f jellygrail to monitor the console output.
• Check http://your-server-ip:16685/status.

Put your custom rclone.conf file

Some Debrid services support are included, but if you have another rclone compatible cloud storage you can add it this way:

• Create a dedicated folder named remote_yourservice.
• Put the rclone file in it.
• The rclone file content should start with [remote_yourservice].
• Check docker run command above (-v /path/remote_yourservice:/mounts/remote_yourservice ) to mount it.

Tip

If the cloud service is not compatible with polling (https://forum.rclone.org/t/which-remotes-support-polling/47445), you can trigger the scan manually with http://your-server-ip:16685/trigger_remote_scan

Kodi Add-on

A Kodi add-on is now provided to ease the Kodi Webdav/SQL configuration process and provide new functionalities.

Add-on installation

Before installing the add-on, please do the following:

• In Settings/Medias/Library:
  • Disable Update library on startup.
  • Enable Ignore different versions on scan (managed by the backend).
  • Disable Ignore video extras on scan.
• In Settings/Medias/Videos, (to increase scanning speed):
  • Disable Extract video information from files.
  • Disable Extract chapter thumbnails.
  • Disable Extract thumnails from video files.

Make sure Webdav is available on your local network : http://your-system-ip:8385:

• Go to Settings > File mananager > Add source > Browse > Add network location > webdav.
• Protocol : WebDAV (HTTP).
• Server address : Your server local ip.
• Port : 8385.
• Click Ok.
• Go back to Settings > Add-ons > Install from zip file.
• In the newly created location browse to actual/kodi/software.
• Click on context.kodi_grail-2026xxxx.zip.

Warning

• If you have custom <video> <sources> nodes in profile/sources.xml, they will be erased.
• If you have custom <videodatabase> nodes in profile/advancedsettings.xml, they will be erased.
• If you want to uninstall, you should manually remove the <videodatabase> node from the profile/advancedsettings.xml file (or erase Kodi install completely).

Add-on features

At installation, the add-on auto detects the Jellygrail server and let you choose the compatible DB among existing ones, otherwise a new DB will be created on the server.

• Long click on a movie or a TVshow season, a contextual manu appears with this item: }{ JeallyGrail Menu at the bottom:

• Functionalities:
  • keep medias
  • check their current local or remote availability
  • Admin actions
  • ... more to come

Usage

1. Verify that you have some torrents in your RD account (JellyGrail does not provide any torrent indexer search or RD downloader).
2. Monitor sudo docker logs -f jellygrail to check for JellyGrail progress or errors.
3. Wait for the ./Video_Library/virtual/ folder to be filled by the scanner.
4. Access the content in ./Video_Library/virtual/ :
   • WebDAV : http://your_system_ip:8385.
   • Jellyfin : http://your_system_ip:8096.
   • or Kodi (see Add-on paragraph above).
5. For Plex you can point your librairies to ./Video_Library/virtual/movies/ and ./Video_Library/virtual/shows/ folders. If you don't need the virtual filesystem functionality, you can as well point your Plex libraries to folders inside ./Video_Library/actual/rar2fs_*/.
6. Beware that JellyGrail restarts by itself at 5.00am 🕡 every wednesday to improve stability.

Folder naming pattern

inside the given mounted sources:

Level 1 folders containing 'movi', 'conc', 'show', or 'disc' will be scanned.

[!TIP] So if you can't rename your local download folder, you can mount it like that:

• -v /path/to/downloads:/mounts/local_whatever/movie_shows_downloads

inside the ./Video_Library virtual folder:

At start, level 1 folders /movies and /shows are created. Do not create other folders on this level (not yet supported).

Troubleshooting

• Jellygrail scans files that are currently downloading.
  • Solution : Configure Bittorrent client to append a temporary extension to uncomplete files.
• Some files are not scanned.
  • Solution : Verify that, inside the given mounted sources, folder names contains movi, conc, disc or show.
• Kodi does not show some posters and pictures.
  • Solution : Long click on an item then }{ JellyGrail Menu then Admin actions > Trigger delta NFO refresh or Trigger full NFO refresh.
• I moved files in the underlying filesystems.
  • Solution : Don't do that or refresh the virtual filesystem right after (see below).
• I created new folder(s) along movies and shows inside the ./Video_Library folder and they're not scanned.
  • Solution : don't do that, it's not supported yet.
• After system restart, container does not start properly.
  • Solution : the rshared mount of folder ./Video_Library/ was probably not creaated, so you have to run ./STOPSTART.SH to fix it.
• Jellyfin stops scanning before reaching 100% : Known issue, see Perforamnce paragraph above.
  • Solution : Relaunch the jellyfin scan inside jellyfin untill it reaches 100% + increase the memory value in docker run command. Avoid complex bluray structures.

Caution

⚠️ If you need to have your virtual folder rebooted with fresh entries, do not delete file items in ./Video_Library/virtual/ folder, as it will also delete corresponding files in the underlying file-systems. Just delete the ./jellygrail/data/bindfs/.bindfs_jelly.db file and restart the docker container

Tip

If you restart your NAS frequently and mounts are not "rshared" by default (like it is in Ubuntu), add STOP.SH script to your shutdown tasks and START.SH script to your startup tasks.

Is the container running ?

sudo docker ps

Container logs

sudo docker logs -f jellygrail

Python service HTTP test

Browse to http://localhost:16685/status

Performance

Jellyfin library scan issues

To workaround Jellyfin issues, the following has been implemented:

• On first setup, LibraryScanFanoutConcurrency = 2.
• LD_PRELOAD /usr/lib/x86_64-linux-gnu/libjemalloc.so.2.
• MALLOC_TRIM_THRESHOLD_ 100000.

JellyGrail optimization

If you have different types of storage, you can override jellygrail specific subfolders with following mountpoints :

• /jellygrail/data/bindfs - SQLite JellyGrail database.
• /jellygrail/data/mariadb - MariaDB db files.
• /jellygrail/vfs_cache - rclone iso/rar structure cache files.

Todo

• 💡inotify sources change detection
• 💡RD backup
• 💡Add audio support
• 💡Proxification compatibility (with automatic fallback to local sqlite kodi DB)
• 💡Call full stack refresh whenever virtual renaming happens (or avoid renaming)
• 💡Fix versions sync progress if set to unwatched in kodi
• 💡Update jellyfin version
• 💡Update rclone version
• 💡Update starlette version
• 💡Sync to *arr metadata + additional virtual FS point dedicated to plex compatible naming pattern
• 💡Native Integration of other cloud services
• 💡Preselect audio/subtitles languages in Kodi DB
• 💡Add DNLA server ?
• 💡Other folders could be created in virtal FS but they must start with 'movies' or 'shows' (make jellfin conf and kodi conf accordingly)
• 💡 When multiple Kodi players are connected and use same DB, refresh UIs of players that did not own the refresh.
• ⚠️When detected as extras, videos are moved into extras subfolder but without their corresponding subtitles if any.
• ⚠️On tablet/mobile android OS, a background Kodi instance will disconnect from network thus add on believes server is down, to fix.
• ⚠️Episode files not inside a directory are currently ignored.
• ⚠️if the Video_Library folder is then accessed through a SMB protocol, renaming/moving does not seem to work (an error pops up) but it's actually working, just refresh the content of the folder and you'll see the renaming is effective. (fix that in bindfs_jelly if possible).
• ⚠️RD Torrents that becomes unavailable (despite rclone fork trying to re-download them) are not fully detected by JellyGrail: corresponding virtual files are not displayed and Jellyfin will thus remove them from library but corresponding parent folders will stay
• ⚠️Underlying files deletion:
  • REMOTE : follows rclone RD fork system : Inside folders containing multiple video files, only 1 file will be deleted (TODO: fix this issue to improve other cloud provider support). In other words it means that underlying files deletion are sometimes uncomplete in this case.
  • LOCAL : Underlying files are deleted but not folders
• ⚠️ deal with m2ts/ts files - maybe at the virtual FS layer to keep only then main m2ts file or let the user choose
• ⚠️ Deletion of a media item which is actually in a RAR file in the underlying file-system will cause the deletion of the whole RAR file.