JellyShip

Self-hosted media platform — Flood torrent UI fork + Jellyfin + smart prefetch engine with FUSE mount and geographic seed diversity scoring.

What is JellyShip?

JellyShip bridges the gap between torrent clients and media servers. Traditional torrent clients download pieces randomly; media servers need sequential, predictable access. JellyShip sits between them with an intelligent prefetch engine that prioritizes downloads based on what you're watching — or about to watch.

Key Features

• Interest Marker System — Unified priority model based on playback state (active, paused, unwatched). Each marker projects a 20-minute preallocation window with gradient priority chunks.
• FUSE Mount — Torrents appear as regular files in a Jellyfin-compatible directory structure. Partial files are streamable; unavailable byte ranges trigger automatic priority boosts.
• Cross-Episode Preloading — When you're 7 minutes from the end of an episode, JellyShip is already downloading the start of the next one.
• Automatic Eviction with Deletion Score — Every file gets a 0-99 score based on demand, seed health, and data freshness. When disk is full, the most expendable content goes first.
• Geographic Seed Diversity — Measures seeder distribution across countries, continents, and autonomous systems. Content with poor diversity scores low for deletion — it resists eviction because the network needs it.
• Peer Observation Database — Tracks all peer interactions with 128-day TTL, freshness-weighted scoring, and background swarm refresh to keep health data current.

Installation

curl -sSL https://raw.githubusercontent.com/bradcarnage/jellyship/main/install.sh | bash

Or manually:

git clone https://forgejo.brads.computer/brad/jellyship.git
cd jellyship
pnpm install
pnpm build
sudo cp configs/jellyship.service /etc/systemd/system/
sudo systemctl enable --now jellyship

Requirements

• Debian 12+ (or any Linux with FUSE support)
• Node.js 22+
• pnpm
• libfuse3-dev
• Jellyfin (optional, for playback integration)

Configuration

Copy the default config and edit:

sudo mkdir -p /etc/jellyship
sudo cp configs/jellyship.default.yaml /etc/jellyship/config.yaml

See docs/preallocation-strategy.md for full configuration reference.

Architecture

Jellyfin Webhooks → Prefetch Engine → torrent-stream → FUSE Mount → Jellyfin Scanner
                         │
                    Eviction Engine
                    ├── Diversity Scorer (GeoIP)
                    ├── Swarm Refresh Scheduler
                    └── Peer Observation DB (NeDB)

Documentation

• Preallocation Strategy — Complete system design, all algorithms, configuration reference
• Handoff Document — Summary and project overview

Tech Stack

Component	Library
Torrent engine	torrent-stream
FUSE mount	fuse-native
GeoIP	MaxMind GeoLite2 + maxmind (npm)
Database	NeDB
Webhook server	Fastify
Config	YAML

License

MIT