████████╗ ██╗ ██████╗   █████╗  ███╗   ███╗ ██╗ ███████╗ ██╗   ██╗
╚══██╔══╝ ██║ ██╔══██╗ ██╔══██╗ ████╗ ████║ ██║ ██╔════╝ ██║   ██║
   ██║    ██║ ██████╔╝ ███████║ ██╔████╔██║ ██║ ███████╗ ██║   ██║
   ██║    ██║ ██╔══██╗ ██╔══██║ ██║╚██╔╝██║ ██║ ╚════██║ ██║   ██║
   ██║    ██║ ██║  ██║ ██║  ██║ ██║ ╚═╝ ██║ ██║ ███████║ ╚██████╔╝
   ╚═╝    ╚═╝ ╚═╝  ╚═╝ ╚═╝  ╚═╝ ╚═╝     ╚═╝ ╚═╝ ╚══════╝  ╚═════╝

_{Tiramisu is the most advanced BitTorrent engine and FUSE virtual filesystem for live streaming to your private Plex or Jellyfin library. Hermes and OpenClaw ready. Forget Real-Debrid.}

[!NOTE]
This project used to be called GoStream. It is now Tiramisu, same project, same codebase, just a new name. Nothing about how it works has changed, and everything in this README still applies. If you are upgrading from an older install, note that the binary name, config paths, and systemd service name have all changed too, so a fresh run of the install script is the easiest way to pick up the new layout.

---

Tiramisu exposes a custom FUSE virtual filesystem where every .mkv file is a perfect illusion: it looks like a real file on disk, but every byte is served live from a BitTorrent swarm on demand. No downloading. No temp files. No storage quota.

The BitTorrent engine runs inside the same OS process as the FUSE layer, connected by an in-memory io.Pipe(). When Plex/Jellyfin reads a byte range, there is no HTTP round-trip, no serialization, no proxy overhead, just bytes, flowing directly from peers through RAM to the media server at full speed.

The result: 4K HDR Dolby Vision, fully seekable, starting in 0.1 seconds, even on a Raspberry Pi 4.

This is not a torrent client with a media server bolted on. The FUSE filesystem is the product, custom-built from scratch around the constraints of torrent streaming: non-sequential byte-range requests, multi-gigabyte files that must be seekable at any position, and a Plex/Jellyfin scanner that probes every file in a library of hundreds of titles on startup.

What's included

The virtual filesystem is the product. Every .mkv in the library is a live
torrent that the media server sees as an ordinary file: the correct size,
seekable, with no temporary copies and nothing downloaded to disk. Below it sits
GoStorm, a deeply patched fork of
TorrServer Matrix and
anacrolix/torrent, running in the
same OS process as the FUSE layer, so there is no HTTP proxy and no serialization
between the swarm and the player. Both upstreams carry streaming patches that do
not exist in the originals.

The library keeps itself up to date. A built-in sync engine, pure Go with no
Python and no external scripts, asks TMDB what is new, trending and popular on a
schedule, searches Prowlarr with Torrentio as fallback, and files the best
release it finds. When a better version appears later, it replaces the old one
automatically: a 1080p entry becomes 4K HDR without anyone asking. TV series
follow the same path, fullpack-first, in a Plex-compatible folder layout. Add a
title to your Plex cloud watchlist and it shows up within the hour.

Your music and audiobooks ride the same filesystem. music/ and
audiobooks/ sit next to movies/ and tv/ under the same mount, served by the
same FUSE layer and filed through the same Library API. An album is added by
exact path with a caller-supplied MusicBrainz or ASIN identity
(external_id + external_id_ns), which is stored in the SQLite projection
registry and written into the virtual file, so a release keeps a real identity
instead of a filename guess. Audio projections are immutable and read-only to
their clients: files answer 0444, directories 0555, and the mutations a
scanner never needs (write open, truncate, rename, mkdir, chmod) are refused
with EROFS, while a direct unlink gets EPERM. Playback is served live from
the swarm exactly like video, so Plex and Plexamp index and play a lossless
album that occupies no disk. FLAC for music; M4B, M4A and MP3 for audiobooks.

Playback quality is the reason for the rest. These pieces exist to turn an
unpredictable swarm into something a media player can trust:

• Adaptive Shield trades a little speed for data integrity only when a peer
  is actually sending bad data, then relaxes once the swarm proves clean. A peer
  that keeps corrupting pieces is banned outright, and the ban is remembered for
  30 days, across restarts.
• TailHedge removes the stutter caused by one slow peer holding up the exact
  byte the player is waiting for, by asking a second peer for the same data and
  using whichever arrives first.
• PEXChurn drops peers that turn out to be useless for the file you are
  actually watching, freeing connection slots for peers that can help.
• Adaptive Chunk Size scales the buffer to what the file needs instead of
  pinning one fixed size for every bitrate.

Everything else is built in, not bolted on. The Control Panel at
:9080/control adjusts every FUSE and engine setting live, and the Health
Monitor Dashboard at :9080/dashboard shows a real-time speed graph, the
active stream with poster and quality badges, sync controls and system stats.
Plex and Jellyfin webhooks are handled natively: media.play switches the
stream to Priority Mode with aggressive piece prioritization, and the IMDB id is
extracted from the raw payload, so localized titles still match. NAT-PMP
lets a WireGuard setup request an inbound port mapping from the VPN gateway and
install the iptables REDIRECT rules, all without a restart. The peer
blocklist is optional and off by default; when enabled it is downloaded at
startup, refreshed every 24 hours, and injected into the engine before any
connection is made. A Library API (/api/library/add, /remove, /list)
lets any HTTP client file or remove a title, movies, series, music and
audiobooks alike, without touching the filesystem, and an
MCP server at /mcp lets an AI agent search, pick and file
releases with the deployment's own scoring profile.
All of it, engine included, ships as a single tiramisu binary.

---

Control Panel

---

Table of Contents

• The Setup: Tiramisu + Plex/Jellyfin/Infuse on Apple TV
• How the Magic Works
• Architecture
• Core Engineering
• Performance
• Requirements
• Quick Install
• How-To Guide
• Control Panel
• Health Monitor
• Configuration Reference
• Sync Engine
• Library API
• MCP Server
• Prowlarr Integration
• Plex/Jellyfin & Samba Setup
• Build from Source
• Docker
• API Reference
• FAQ
• Troubleshooting
• Donate
• License

---

The Setup: Tiramisu + Plex/Jellyfin/Infuse on Apple TV

Not a developer? This section explains what you actually get and why it works so well.

The end result: you open Infuse on your Apple TV, your entire movie library appears with posters and metadata, you press Play on a 4K Dolby Vision film and it starts in under a second. No buffering. No "downloading...". No subscription to Real-Debrid or any external service. Everything runs on a single board computer or any always-on Linux box in your home.

How the three pieces fit together

Tiramisu runs on your Linux device, a Raspberry Pi, a NAS, a VPS, or any always-on machine. It creates a virtual hard drive that looks completely real to the rest of your network: it contains thousands of .mkv files, each the correct size, each seekable. In reality, none of those files exist on disk. When anything reads a byte, Tiramisu silently fetches it in real-time from the BitTorrent network and passes it through.

Plex (or Jellyfin, or any media server) sees this virtual hard drive as a normal media library. It scans the files, downloads posters and descriptions from the internet, tracks what you've watched, and makes everything available on your home network, just like it would with a real NAS.

Infuse on Apple TV connects to your Plex/Jellyfin library and plays the files using Direct Play: it reads the video stream directly from the file, with no conversion or re-encoding. This is why it handles 4K HDR Dolby Vision effortlessly, even though it is coming from a torrent in real time.

Because Tiramisu exposes standard .mkv files on a standard filesystem, any player or media server that can read a network share works: Plex, Jellyfin, Emby, Kodi, VLC, mpv, or anything else. No plugins, no special configuration.

How your library gets populated automatically

Tiramisu includes a built-in sync engine that runs on a schedule and keeps your library up to date without any manual intervention.

Every day, the engine queries TMDB (The Movie Database) for the latest releases, trending titles, and popular movies. For each title it finds, it searches Prowlarr (with Torrentio fallback) for the best available torrent (preferring 4K Dolby Vision, falling back to 1080p). If a good torrent is found, it registers it in GoStorm and creates the corresponding virtual .mkv file in the library.

The next time the media server scans, it finds a new file, downloads the poster and description, and the film appears in your library ready to play.

If a better version of a film becomes available later (for example a 4K HDR release of a title you already have in 1080p), the engine replaces it automatically.

TV series work the same way: the sync engine finds new seasons and episodes, organises them in the Plex/Jellyfin-compatible folder structure (Show Name (Year)/Season.01/), and they appear in your library within the week.

You can also add a title to your Plex Watchlist from any device and it will appear in your library within the hour.

Prowlarr Integration (Resilience)

To ensure the system remains functional even when public aggregators like Torrentio are down, Tiramisu includes a Prowlarr Adapter. This allows you to use your own self-hosted Prowlarr instance as the primary source for torrents.

The sync engine implements a Strict Fallback logic: it first queries your Prowlarr indexers using IMDB IDs for maximum precision. If no results are found locally, it automatically falls back to Torrentio.

Configuration is done via config.json (or the Control Panel → Prowlarr Indexer section):

"prowlarr": {
  "enabled": true,
  "api_key": "your-api-key",
  "url": "http://192.168.1.x:9696"
}

See the Prowlarr Adapter Documentation for technical details.

100% local, no subscriptions

Tiramisu has no external dependency at playback time. No third-party service, no monthly fee, no data leaving your home. Your library is always available, even without an internet connection, and it never disappears because a remote service went down.

Why Infuse starts in under a second

When you press Play, Infuse immediately reads the beginning and end of the file to load the video index and seek tables. On a real hard drive this is instant. Tiramisu replicates this with an SSD warmup cache: the first 64 MB and last few MB of every file are pre-cached on the Pi's SSD during the initial Plex/Jellyfin library scan. By the time you press Play, those bytes are already on disk and Infuse gets them in milliseconds.

Why your library survives a reboot

Every file on a real filesystem has a permanent ID called an inode. Plex/Jellyfin and Infuse use these IDs to recognize files across restarts, so they know "this is the same film I scanned last week" and do not re-download metadata or reset your watch history.

On a standard virtual filesystem, these IDs are random and change every time the system restarts. Tiramisu solves this by persisting a permanent inode map to a SQLite database (STATE/tiramisu.db). After a reboot, every virtual .mkv gets back the exact same ID it had before. To Plex/Jellyfin and Infuse, it is indistinguishable from a file that never moved.

When you press Play: the full chain

You tap Play on Infuse, and Infuse asks Plex (or Jellyfin) for the file. Plex
reads it from Tiramisu's virtual filesystem, which is where the illusion ends:
the media server also fires a webhook at Tiramisu saying "user started playing
this film". Tiramisu matches the event to a torrent and switches that stream to
Priority Mode, so every spare byte of bandwidth goes to the film you are
watching and background activity pauses. From there the bytes travel the only
path they ever take: from BitTorrent peers into Tiramisu's memory, through the
FUSE layer to Plex, from Plex to Infuse, and onto the TV. If you seek, the same
machinery jumps straight to the new position in the torrent instead of
re-buffering from the beginning.

---

How the Magic Works

Plex/Jellyfin reads /mnt/tiramisu-mkv-virtual/movies/Interstellar.mkv. From Plex/Jellyfin's perspective, it's a normal 55 GB file on a local disk. In reality, the file does not exist. The FUSE kernel module intercepts the read, calls into Tiramisu, and Tiramisu serves the exact bytes from a three-layer cache, backed by a live BitTorrent swarm.

Layer	What	Size	Purpose
L1	In-memory Read-Ahead	256 MB	32-shard concurrent buffer with per-shard LRU
L2 (optional)	SSD Warmup Head	64 MB/file	Instant TTFF on repeat playback, served at 150–200 MB/s from SSD
L3 (optional)	SSD Warmup Tail	16 MB/file	MKV Cues (seek index), Plex/Jellyfin probes the end of every file before confirming playback

What makes this non-trivial: a FUSE filesystem that backs a real directory of static files is straightforward. A FUSE filesystem that must handle non-sequential byte-range requests across hundreds of files, each backed by an independent torrent with variable peer availability, while a Plex/Jellyfin scanner hammers every inode in parallel: that required building every subsystem from scratch.

---

Architecture

BitTorrent Peers ←→ GoStorm Engine (:8090)
                         │
              Native Bridge (In-Memory Pipe)
              Zero-Network, Zero-Copy Hot Path
                         │
         ┌───────────────────────────────────┐
         │       Tiramisu FUSE Layer         │
         │  L1: Read-Ahead Cache (256 MB)    │
         │  L2: SSD Warmup Head (64 MB/file) │
         │  L3: SSD Warmup Tail (16 MB/file) │
         └───────────────────────────────────┘
                         │
         /mnt/tiramisu-mkv-virtual/*.mkv  (FUSE mount)
                         │
         Samba share (smbd, oplocks=no, vfs objects=fileid)
                         │
         Synology CIFS mount (serverino, vers=3.0)
                         │
         Plex/Jellyfin Media Server libraries

Port Map

Port	Purpose
:8090	GoStorm API, JSON torrent management
:9080	Control Panel, Metrics, Dashboard, Webhook, Scheduler, Library API

---

Core Engineering

Eleven purpose-built subsystems, each one the answer to a problem that
surfaced while running this on Raspberry Pi 4 hardware.

A media server gives a streaming engine no second chances: it opens many files
at once, reads the end of a file before the beginning, seeks wherever the user
drags the bar, and expects the bytes to be there. On a Pi the margin is thin, so
every subsystem below exists to remove one specific way the illusion can break.

1. Zero-Network Native Bridge

Tiramisu is one process, not two. The GoStorm engine and the FUSE layer are
compiled into the same binary, so when the media server asks for a byte range
the FUSE side calls straight into the engine through an in-memory io.Pipe().
There is no TCP round trip, no HTTP headers to parse, no serialization and no
proxy in the middle; metadata lookups are plain Go function calls. That is what
removes the network latency that makes HTTP-based streaming proxies stutter on
small hardware.

2. Two-Layer SSD Warmup Cache (optional)

An optional SSD cache that makes repeat playback almost instant. It is enabled
and configured from the Control Panel → GoStorm settings, and it is independent
of the core streaming path: without it Tiramisu still works, it just pays the
cold-start cost again.

When enabled, the head cache keeps the first 64 MB of each file on SSD from
the first play onward, so a repeat playback opens in under 0.01 s (an SSD
reads at 150–200 MB/s, against 2–4 s for a cold torrent activation). The tail
cache keeps the last 16 MB separately: MKV files store their Cues, the seek
index, near the end, and the media server probes that region before confirming
playback, which is why without it the seek bar can render as unavailable on the
first open. The quota is configurable by LRU write time; the reference
Raspberry Pi deployment uses 32 GB, enough for around 400 films. No manual
warming is needed: a library scan reads the first 1 MB of every file, which is
exactly what the head cache needs.

3. Webhook Integration & Smart Streaming

Tiramisu listens for the media server's "user pressed Play" event at
:9080/plex/webhook (the shorter /webhook works too), for Plex and
Jellyfin alike. When media.play arrives, four things happen at once: the
IMDB id is pulled out of the raw payload, the pieces covering the byte range
being played are given priority, the MKV Cues at the end of the file are frozen
so a seek does not have to fetch them again, and when playback stops the torrent is kept for 30 s, or for 5 s when it was only a scanner probe no webhook ever confirmed, so ordinary library traffic releases its peers almost at once.

The IMDB id is extracted with a regex before the payload is decoded, and that
is deliberate: Plex sends its identifiers in a non-standard Guid array that
makes a normal json.Unmarshal fail silently. The id is also what makes the
match language-independent, because media servers send titles in the user's
display language ("den stygge stesøsteren" instead of "The Ugly Stepsister")
and fuzzy matching fails on exactly those cases.

Plex: Settings → Webhooks → Add Webhook:

http://<your-pi-ip>:9080/plex/webhook

Jellyfin: install the
Webhook plugin, then add
one webhook with the events PlaybackStart, PlaybackStop and
PlaybackProgress:

Field	Value
URL	http://<your-pi-ip>:9080/plex/webhook
Header Key	Content-Type
Header Value	application/json

Template:

{"event":"{{NotificationType}}","Metadata":{"title":"{{{Name}}}","grandparentTitle":"{{{SeriesName}}}","librarySectionType":"{{ItemType}}","guid":"imdb://{{Provider_imdb}}","Guid":[{"id":"imdb://{{Provider_imdb}}"}]}}

Jellyfin's own event names and item types are mapped onto Tiramisu's internally
(PlaybackStart→media.play, PlaybackStop→media.stop, Movie→movie,
Episode→show), so neither side needs a code change or a plugin hack.

Music uses the same endpoint with a different identity: a track has no IMDb id,
so Tiramisu matches on the MusicBrainz id the projection was filed with. Plex and
Plexamp need no extra configuration: play an album and the log shows
[PLEX] Playback confirmed by webhook for: <file>.flac. Jellyfin needs a second
Generic destination (Jellyfin 10.11 requires plugin 18 or later, 10.10 requires 16
or later, current is 22) with the same URL and events and this body:

{"event":"{{NotificationType}}","Metadata":{"title":"{{{Name}}}","grandparentTitle":"{{{Artist}}}","librarySectionType":"{{ItemType}}","ProviderIds":{"MusicBrainzTrack":"{{Provider_musicbrainztrack}}","MusicBrainzReleaseGroup":"{{Provider_musicbrainzreleasegroup}}","MusicBrainzAlbum":"{{Provider_musicbrainzalbum}}","MusicBrainzArtist":"{{Provider_musicbrainzartist}}"}}}

Plex sends the release track id, Jellyfin the recording id (the MUSICBRAINZ_TRACKID
tag, exposed as MusicBrainzTrack). The id style follows the Plex/Jellyfin switch in
the Control Panel, so a library must be filed with the style of the player that
actually plays it, and switching player afterwards means re-filing it with an align
run in the new style. Jellyfin exposes MusicBrainz providers only when the files
carry MusicBrainz tags: tagless files still play, but their webhook has no id to
match and the session falls back to inferred playback.

4. Adaptive Shield

Two read modes, managed automatically:

Mode	Behavior	When
Responsive (default)	Data served before SHA1 verification, instant start	Normal operation
Strict	Only SHA1-verified pieces served	Automatically activated on corruption detection

Responsive is the default because it is what makes playback start instantly:
bytes go out before their SHA1 is checked. When a corrupt piece is detected
(MarkNotComplete()), the shield switches to Strict and serves only verified
data, then waits for a clean streak before relaxing again. The streak starts at
30 seconds and grows by another 30 each time Strict re-triggers, up to a cap of
30 minutes; the first corruption in a session only logs and bans the peer,
leaving Fast mode on. The counter clears on a genuine clean streak, not on
seeks or a media.stop, so a swarm that keeps sending bad pieces gets
progressively more scrutiny instead of restarting the same short timer.
A peer that keeps corrupting is banned outright, and the ban is remembered for
30 days, across restarts. The mode switch itself is an atomic boolean, so the
hot read path pays no lock.

5. Seek-Master Architecture

Seeking is the hardest thing a player can ask for: the target can be gigabytes
away from where the pump is reading, and the player will not wait. Five
coordinated fixes make it feel local:

Fix	What it does
Eager offset update	Updates lastOff before the cache check, so the pump sees the target on the same Read() call
Atomic pipe interrupt	Interrupt() closes the pipe reader atomically when the player jumps > 256 MB, unblocking an io.ReadFull that is already waiting
Reactive jump	If the player is > 256 MB ahead of the pump, snap to (playerOff / chunkSize) * chunkSize
Pump survival	The pump survives ErrInterrupted with a 200 ms sleep-and-continue, with no goroutine restart
Tail probe detection	The media server's end-of-file MKV Cues probe is served from the SSD tail cache without steering the pump

None of them works alone: the offset update tells the pump where the reader is
going, the interrupt unblocks a read in flight, the reactive jump covers the
huge gaps, the pump survives the interruption instead of being torn down, and
the Cues probe is recognised as a probe rather than allowed to drag the pump to
the end of the file.

6. 32-Shard Read-Ahead Cache

The 256 MB read-ahead budget is not one lock-protected structure. It is split
across 32 independent shards, keyed by a hash of file path and offset, each
with its own LRU and mutex, so concurrent playback sessions and the media
server's scanner threads never stand in line behind one another. Both Put()
and Get() work on defensive copies: returning a sub-slice of a pooled
buffer means the next user of that buffer can overwrite data somebody is still
reading, which is exactly the kind of corruption that reaches the player as a
stutter.

7. Native Sync Engine (Go)

All sync logic runs inside the Go binary: no Python, no external scripts, no
subprocess to babysit.

Engine	Trigger	What it does
Movies	Scheduler / manual	TMDB Discover + Popular → Prowlarr/Torrentio → GoStorm → virtual .mkv
TV Series	Scheduler / manual	TV series with fullpack-first approach, episode registry
Watchlist	Scheduler / manual	Plex cloud watchlist → IMDB → Prowlarr/Torrentio → GoStorm
Music	Scheduler / manual	New albums of your artists + new artists close to yours + niche artists of your genres + similar artists (Deezer) → MusicBrainz → Prowlarr → FLAC projections

Quality ladder: 4K DV > 4K HDR10+ > 4K HDR > 4K > 1080p REMUX > 1080p
Minimum seeders: 15, for the main sync and the watchlist alike (the watchlist uses the movie profile)

Everything the engine needs to remember, the episode registry, the negative
caches and the scheduler state, is persisted in STATE/tiramisu.db (SQLite).
The built-in scheduler replaces system cron, and it is configured from the
Control Panel.

8. NAT-PMP Native VPN Port Forwarding

Behind a WireGuard tunnel the home router's port forwarding no longer applies,
because the traffic leaves through the VPN gateway instead. Tiramisu runs a
NAT-PMP sidecar that periodically asks the gateway for a TCP+UDP port mapping,
installs the iptables PREROUTING REDIRECT rules that point the mapping at the
local listener, and updates GoStorm's listen port. All of it at runtime: no
restart, no manual rule editing.

9. IP Blocklist (optional)

Off by default. When blocklist_enabled is set, Tiramisu downloads a gzipped
blocklist at startup, refreshes it every 24 hours, and injects the ranges
straight into anacrolix/torrent's IP filter, so a known-bad actor is refused
before any connection attempt. Compression is detected from the content, so a
URL that serves gzip without a .gz extension still works, and a download that
yields no usable ranges is discarded rather than replacing a working list.

Published lists need care, which is why the filter exists. iblocklist Level 1
carries around 236,000 ranges covering 17% of IPv4, and most of it comes
from whois records dating to the 1990s: entire /16s still attributed to
companies that sold the address space years ago. Loaded whole, it rejects
ordinary peers, not monitoring outfits. blocklist_filter is a regexp over the
entry's description that keeps only the part still maintained:

"blocklist_url": "https://list.iblocklist.com/?list=ydxerpxkpcfqjaybcssw&fileformat=p2p&archiveformat=gz",
"blocklist_filter": "(?i)\\bap2p\\b|anti-?p2p"

That turns 236,172 ranges into 5,134, from 17% of IPv4 down to 0.03%.
Leave the filter empty to load a list whole; aggregate lists that mix anti-P2P,
ads, malware and whole-country blocks can reject almost every peer and stop
playback from starting at all. GET /metrics/blocklist reports how many
addresses were rejected and which ranges did the rejecting, which is the only
honest way to tell a list that earns its keep from one quietly eating good
peers.

10. Profile-Guided Optimization (PGO)

The binary is built with -pgo=auto, so the Go toolchain reads default.pgo
and uses real production profiling data to inline hot paths and lay out
branches. On a Pi 4 Cortex-A72, which has no hardware AES or SHA1, PGO alone is
worth roughly 5–7% of CPU.

11. GoStorm Engine: a deep fork of TorrServer Matrix + anacrolix/torrent

GoStorm is a fork of TorrServer Matrix
(BitTorrent management layer) and
anacrolix/torrent (peer
protocol engine). Both upstreams have been patched extensively for streaming
correctness and performance, in ways that are not present in the originals:

Click to expand: 15+ targeted optimizations

Optimization	Problem → Solution
O(1) AddTorrent DB write	Original rewrote all 520 torrents on every add (O(N) fsync). Fixed to single tdb.Set().
O(1) GetTorrentDB	Original called ListTorrent() + 520 unmarshals to find one torrent. Fixed to direct key lookup.
InfoBytes + PeerAddrs caching	TorrentSpec.InfoBytes was never persisted, re-activation required full metadata fetch. Now saved on Wake().
Request rebuild debounce	300 rebuilds/s reduced to 60 → 5x CPU reduction.
O(1) clearPriority	Original iterated all ~512 cached pieces with global lock. Replaced with localPriority map tracking ~25 active pieces.
4 MB MemPiece buffer zeroing	Channel pools reused buffers without zeroing → stale data from different files caused forward-jump corruption. Fixed with clear(p.buffer).
raCache defensive copies	Get() returned sub-slices of pooled buffers. On eviction, Plex/Jellyfin received overwritten data. Fixed with copies on Put() and Get().
cleanTrigger panic fix	Cache.Close() closed the channel while goroutines could still send → panics during peer upload. Fixed with separate cleanStop channel.
PeekTorrent discipline	Monitoring endpoints using GetTorrent() caused silent torrent activation loops. All monitoring paths now use PeekTorrent().
InodeMap GC fix	Inode cleanup pruned virtual MKV stubs every 5 min (529 files). Fixed to use WalkDir(physicalSourcePath).
8 additional race condition fixes	Concurrent map writes, torn reads, nil pointer dereferences across requesting.go, piece.go, cache.go, apihelper.go.

---

Performance

Measured on a Raspberry Pi 4 (4 GB RAM, Cortex-A72, arm64, no hardware
crypto), the minimum supported baseline. On amd64 or a more powerful arm64 box
the numbers are better.

The experience in two lines: a first play from a cold swarm takes 2–4 seconds, a
repeat play from the SSD warmup cache opens in a fraction of a second, and 4K
HDR playback costs about a fifth of one core. The table is the detail behind
those two.

Metric	Value
Cold start (first play, no warmup)	2–4 s
Warm start (SSD warmup HIT)	0.1–0.5 s
Seek latency (cached position)	< 0.01 s
CPU at 4K HDR streaming	20–23% of one core
CPU reduction vs. baseline	−87% (161% → 20%)
Binary size	33 MB (60% smaller than legacy builds)
Memory footprint (read-ahead)	Deterministic 256 MB
GOMEMLIMIT	2200 MiB
Peak throughput (fast seeder)	400+ Mbps
Plex/Jellyfin scan peer count	~6 total (was ~15,000 before fix)
Inode shard count	32 (collision-protected)
Warmup cache capacity	~400 films at 80 MB each (32 GB)

---

Requirements

Component	Details
Hardware	Any linux/amd64 or linux/arm64 device, Raspberry Pi 4 is the minimum tested baseline (4 GB RAM recommended). Runs on NAS, VPS, mini-PC, or any always-on Linux box. On amd64, AVX2 is strongly recommended (any x86_64 CPU from ~2013 onward, Intel Haswell or AMD Excavator and later). Without it, Go's SHA1 piece verification falls back to its slowest scalar path and may not sustain real playback bitrates; Tiramisu still starts, logging a warning at boot so high CPU and stuttering have a visible cause. arm64 has no equivalent requirement: NEON is mandatory on every ARMv8-A chip, so any real arm64 device, the Pi 4 included, already clears the floor.
Go	1.26+ (linux/amd64 or linux/arm64), do not use the 32-bit linux/arm toolchain. Build with CGO_ENABLED=1: the SQLite piece-completion layer is cgo
FUSE 3	sudo apt install fuse3 libfuse3-dev
systemd	For service management
Samba	sudo apt install samba
Plex/Jellyfin	Media Server (on Synology or any network host)
TMDB API key	Free at themoviedb.org/settings/api
Plex token	Settings → Account → XML API

---

Quick Install

curl -fsSL https://raw.githubusercontent.com/MrRobotoGit/tiramisu/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

The interactive installer handles everything end-to-end:

1. Installs system dependencies (fuse3, libfuse3-dev, gcc, samba, git)
2. Prompts for all required paths, Plex credentials, TMDB key, and NAT-PMP settings
3. Generates config.json from config.json.example
4. Creates Tiramisu/STATE/, logs/, and FUSE mount point directories
5. Compiles the Tiramisu binary (downloads Go if needed, detects architecture automatically)
6. Writes and enables the systemd service for tiramisu

Once complete:

sudo systemctl start tiramisu

---

How-To Guide

[!CAUTION]
Attention: After the first run of the Movie and TV sync engine, hundreds of .mkv files will be created. Plex/Jellyfin will then begin scanning these files to populate its UI. During this initial scan, playback will be extremely slow or may time out. This is because the media server opens and closes files hundreds of times during analysis, which congests the BitTorrent engine. Please wait for Plex/Jellyfin to complete its scan before starting any streams. Enjoy!

Step 1: Configure the Webhook (Plex or Jellyfin)

Required for Priority Mode (bitrate boost during playback), fast-drop on stop, and IMDB-ID-based file matching.

Plex: Settings → Webhooks → Add Webhook:

http://192.168.1.2:9080/plex/webhook

Jellyfin: Install the Webhook plugin, add one webhook (events: PlaybackStart, PlaybackStop, PlaybackProgress):

• URL: http://192.168.1.2:9080/plex/webhook
• Header: Key Content-Type / Value application/json
• Template:

{"event":"{{NotificationType}}","Metadata":{"title":"{{{Name}}}","grandparentTitle":"{{{SeriesName}}}","librarySectionType":"{{ItemType}}","guid":"imdb://{{Provider_imdb}}","Guid":[{"id":"imdb://{{Provider_imdb}}"}]}}

Music needs a second Generic destination with its own template, same URL and events:

{"event":"{{NotificationType}}","Metadata":{"title":"{{{Name}}}","grandparentTitle":"{{{Artist}}}","librarySectionType":"{{ItemType}}","ProviderIds":{"MusicBrainzTrack":"{{Provider_musicbrainztrack}}","MusicBrainzReleaseGroup":"{{Provider_musicbrainzreleasegroup}}","MusicBrainzAlbum":"{{Provider_musicbrainzalbum}}","MusicBrainzArtist":"{{Provider_musicbrainzartist}}"}}}

Test connectivity:

curl -X POST http://192.168.1.2:9080/plex/webhook \
  -H 'Content-Type: application/json' \
  -d '{"event":"media.play"}'

Step 2: Configure the Plex/Jellyfin Library

Add a Movies library in Plex/Jellyfin pointing to the Samba share:

smb://192.168.1.2/tiramisu-mkv-virtual/movies

Or, if using Synology, point Plex/Jellyfin to the CIFS mount: /volume1/Tiramisu/movies.

Run a library scan after adding the library. Plex/Jellyfin reads the first megabyte of every .mkv file during the scan, this automatically populates the SSD warmup head cache for every title. Subsequent plays will start in under 0.5 seconds.

Step 3: Add Your First Movie

Manually via API:

curl -X POST http://127.0.0.1:8090/torrents \
  -H "Content-Type: application/json" \
  -d '{"action":"add","link":"magnet:?xt=urn:btih:...","title":"Interstellar (2014)"}'

Via sync engine (recommended):
Trigger from the Control Panel (:9080/control) → Sync Scheduler → Movies → "Run now", or via API:

curl -X POST http://127.0.0.1:9080/api/scheduler/movies/run

The engine fetches popular films from TMDB, finds the best available torrent for each via Prowlarr/Torrentio, adds them to GoStorm, and writes virtual .mkv stub files.

Step 4: Watch a Film (What Happens Internally)

1. Plex/Jellyfin requests /mnt/tiramisu-mkv-virtual/movies/Interstellar.mkv
2. FUSE Open() triggers Wake(), GoStorm activates the torrent
3. Plex/Jellyfin metadata probes → served from SSD warmup cache if enabled, otherwise from the torrent pump
4. Plex/Jellyfin probes MKV Cues at end → served from SSD tail cache if enabled
5. Plex or Jellyfin sends media.play webhook → Tiramisu activates Priority Mode
6. Streaming reads → served from Read-Ahead Cache or Native Bridge pump
7. Playback begins (0.1–0.5 s with warmup, 2–4 s cold) ✨

Step 5: Seek in 4K

When Plex/Jellyfin seeks to a new timestamp:

1. Read() is called at the new offset, lastOff is updated immediately
2. If the jump exceeds 256 MB: Interrupt() closes the pipe, pump goroutine unblocks atomically
3. Pump detects lastOff is > 256 MB ahead, snaps to aligned chunk position
4. Pump restarts via startStream(newOff), GoStorm repositions torrent reader
5. Data arrives from peers or SSD cache within seconds

The pump goroutine survives ErrInterrupted, it sleeps 200 ms and continues the read loop, so no goroutine restart overhead.

Step 6: Add from Your Plex Watchlist

Add any movie to your Plex cloud watchlist (desktop or mobile app). Within the interval configured in the Scheduler (default: 1 hour), the Go sync engine will resolve it to an IMDB ID, find the best torrent, and add it automatically.

Trigger manually from the Control Panel (:9080/control) → Sync Scheduler → Watchlist → "Run now", or via API:

curl -X POST http://127.0.0.1:9080/api/scheduler/watchlist/run

The engine:

1. Queries discover.provider.plex.tv for your watchlist
2. Resolves each entry to an IMDB ID (falls back to TMDB)
3. Queries Prowlarr/Torrentio for the best stream (minimum 10 seeders)
4. Adds to GoStorm and writes a virtual .mkv stub

Step 7: Monitor in Real Time

# Control Panel, Tiramisu + GoStorm settings, paths, scheduler, restart button
open http://192.168.1.2:9080/control

# Health Dashboard, speed graph, torrent stats, active stream, system stats
open http://192.168.1.2:9080/dashboard

# Raw metrics (JSON)
curl -s http://192.168.1.2:9080/metrics | python3 -m json.tool

# Scheduler status
curl -s http://192.168.1.2:9080/api/scheduler/status | jq

# Live log key events only
ssh [email protected] "tail -f /home/pi/Tiramisu/logs/tiramisu.log | grep -E '(OPEN|NATIVE|Interrupt|Jump|DiskWarmup|Emergency)'"

# Active torrents in RAM with speed
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"action":"active"}' http://192.168.1.2:8090/torrents | \
  jq '.[] | {title: .title[:60], speed_mbps: ((.download_speed//0)/1048576|round), peers: (.active_peers//0)}'

Step 8: Configure the MKV Creation Scheduler

Tiramisu includes a built-in scheduler that replaces system cron. Configure it from the Control Panel at :9080/control → Sync Scheduler card.

Three jobs are available:

Job	Default schedule	Log file
Movies Library Sync	Mon + Thu at 03:00	logs/movies-sync.log
TV Series Libraries Sync	Wed + Fri at 04:00	logs/tv-sync.log
Plex Watchlist Sync	Every 1 hour	logs/watchlist-sync.log

Enable the scheduler with the Enable Scheduler toggle, pick weekdays and start time for each job, then click Save schedule. Changes require a service restart to take effect.

Run now: trigger any job immediately from the Control Panel or via POST /api/scheduler/{type}/run on port 9080.

Step 9: Tune GoStorm Settings

Via the Control Panel at :9080/control, or via API:

curl -X POST http://127.0.0.1:8090/settings \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set",
    "sets": {
      "CacheSize": 100663296,
      "ReaderReadAHead": 95,
      "PreloadCache": 0,
      "ConnectionsLimit": 25,
      "TorrentDisconnectTimeout": 10,
      "UseDisk": true,
      "ResponsiveMode": true
    }
  }'

Setting	Value	Rationale
CacheSize	96 MB	Lean engine strategy, feed FUSE 256 MB buffer; smaller heap = lower GC. 64 MB caused buffering in testing.
ConnectionsLimit	25	Matches FUSE master semaphore; prevents Samba thread exhaustion
ResponsiveMode	true	Serve unverified data; Adaptive Shield corrects corruption automatically
UseDisk	true	Enable SSD warmup cache
TorrentDisconnectTimeout	10 s	Fast peer cleanup for RAM footprint

Step 10: Regenerate the PGO Profile

Capture a CPU profile during real streaming workload:

# Single profile (120 seconds while streaming a 4K film)
curl -o ~/Tiramisu/default.pgo \
  "http://127.0.0.1:9080/debug/pprof/profile?seconds=120"

# Or merge multiple workloads for better coverage
curl -o /tmp/pgo-stream.pprof "http://127.0.0.1:9080/debug/pprof/profile?seconds=120"
curl -o /tmp/pgo-sync.pprof   "http://127.0.0.1:9080/debug/pprof/profile?seconds=120"
go tool pprof -proto /tmp/pgo-stream.pprof /tmp/pgo-sync.pprof > ~/Tiramisu/default.pgo

# Rebuild Go detects the changed profile and re-optimizes automatically
cd ~/Tiramisu
GOARCH=arm64 CGO_ENABLED=1 /usr/local/go/bin/go build -pgo=auto -o tiramisu .

Regenerate after significant code changes. On Pi 4 Cortex-A72, sha1.blockGeneric in the profile is expected: the A72 has no hardware SHA1 extensions.

---

Tiramisu Control Panel

The Control Panel is where you tune the engine, point it at your paths and
credentials, run a sync by hand and restart the service, all without opening
config.json or an SSH session. It is a web UI embedded in the Tiramisu
binary: no additional server, no React build step, no external dependencies.
Served at :9080/control.

http://<your-pi-ip>:9080/control

Simple / Advanced Mode

A toggle in the top-right corner switches between two views:

• Simple: Most frequently changed settings: read-ahead budget, concurrency, cache size, paths, and NAT-PMP toggle
• Advanced: All tunable parameters, split into labelled groups across two panels

Tiramisu FUSE Panel (left)

Settings are written to config.json and require a service restart. The Restart button in the header triggers an immediate restart.

Group	Settings
Core & Streaming	ReadAhead Budget (MB), Master Concurrency, Max Streaming Slots, Streaming Threshold (KB)
Paths	Physical Source Path (Samba root), FUSE Mount Path
Prowlarr Indexer	Enable Prowlarr, API Key, URL
Media Manager (Plex)	TMDB API Key, Plex URL, Plex Token, Movies Library ID, Series TV Library ID
Connectivity & Rescue	GoStorm URL, Rescue Grace/Cooldown, Metrics Port, Log Level, Tiramisu Port, Enable BlockList, BlockList URL

GoStorm Engine Panel (right)

Settings are pushed live via API: no restart needed. Apply All Core Settings sends values immediately.

Group	Settings
Cache & Data	Cache Size (MB), Readahead Cache (%), Preload Cache (%)
Warmup & SSD	Use Warmup Cache, Warmup path, SSD Quota (GB), Head Warmup (MB)
Swarm Limits	Connections Limit, DL/UP Rate (KB/s), Disconnect Timeout (s)
Network & Protocol	Listen Port, Retrackers Mode, IPv6/DHT/PEX/TCP/uTP/Upload/Force Encrypt
NAT-PMP (WireGuard)	Enable, Gateway IP, VPN Interface, Refresh/Lifetime (s), Local Port
Behaviors	Smart Responsive Mode, Debug Log

---

Health Monitor Dashboard

Embedded Go service at port :9080. Real-time operational view of the entire
stack: one page that answers "is it healthy right now, and what is it doing",
without reading a log.

http://<your-pi-ip>:9080/dashboard

Status Grid

Six cards in a 2×3 grid:

Card	What it shows
GOSTORM	API ping latency (green = responding). Restart button.
FUSE MOUNT	Number of virtual .mkv files currently exposed.
VPN (WG0)	WireGuard interface status: VPN IP and gateway.
NAT-PMP	Active external port assigned by VPN gateway.
PLEX	Server version and reachability.
SYSTEM	CPU %, RAM %, free disk space, live via gopsutil.

Download Speed Graph

15-minute rolling chart of GoStorm download speed in Mbps. Samples every 5 seconds with auto-scroll.

Active Stream Panel

Appears automatically during playback:

• 🎬 Movie poster (fetched from TMDB)
• 🏷️ Quality badges: PRIORITY, 4K, DV, ATMOS, HDR10+
• 📡 LIVE indicator + 5-minute average speed
• 👥 Peer/seeder count for the active torrent

Sync Controls

Two panels for manual sync execution without SSH:

• MOVIES SYNC: Triggers the Go movie sync engine with live log streaming
• TV SYNC: Triggers the Go TV sync engine with Start/Idle status

MKV Creation Scheduler

Built into the Go binary. Configured from the Sync Scheduler card in the Control Panel:

• Movies Library Sync: select weekdays + start time
• TV Series Libraries Sync: select weekdays + start time
• Plex Watchlist Sync: interval-based (1 h, 2 h … 24 h)

Last/next run times and live status are shown in the card. State persists across restarts in STATE/tiramisu.db.

---

Configuration Reference

config.json is resolved relative to the binary's path (os.Executable()), so
no path argument is needed, and it is not tracked by git because it holds
credentials. In practice you rarely edit it by hand: the Control Panel writes
the same file, with FUSE and path settings applied at the next restart and
engine settings applied live.

cp config.json.example /home/pi/Tiramisu/config.json
nano /home/pi/Tiramisu/config.json

Full Field Reference

Field	Default	Description
physical_source_path	(none)	Directory where virtual .mkv stubs are created
fuse_mount_path	(none)	FUSE mount point, seekable virtual files served here
read_ahead_budget_mb	256	In-memory read-ahead budget
disk_warmup_quota_gb	15	SSD warmup cache quota; the reference Raspberry Pi deployment raises it to 32 GB
warmup_head_size_mb	64	Per-file SSD warmup size
master_concurrency_limit	25	Max concurrent data slots
metadata_cache_size_mb	50	Metadata LRU cache budget
fuse_max_inflight_mb	0	Cap on the RAM go-fuse checks out for in-flight requests; 0 leaves go-fuse's own default
gostorm_url	http://127.0.0.1:8090	GoStorm internal API URL
proxy_listen_port	8080	Legacy field kept for config compatibility: no listener uses it today
metrics_port	9080	Metrics, Control Panel, Webhook port
media_server_type	plex	plex or jellyfin; selects how the post-sync library refresh is issued and which API the music sync reads
torrentio_url	https://torrentio.strem.fun	Torrentio base URL, the fallback when Prowlarr is disabled or finds nothing
blocklist_enabled	false	Load the peer IP blocklist (not needed behind a VPN)
blocklist_url	(iblocklist Level 1)	Gzipped blocklist URL, refreshed every 24 h; compression is detected from the content
blocklist_filter	(?i)\bap2p\b|anti-?p2p	Keep only ranges whose description matches this regexp; empty loads the list whole
plex.url	(none)	Media server URL: Plex or Jellyfin
plex.token	(none)	Plex token, or Jellyfin API key
plex.library_id	0	Plex movies library section ID (0 = skip the refresh)
plex.tv_library_id	0	Plex TV series library section ID (0 = skip the refresh)
plex.music_library_id	0	Plex music library section Tiramisu files into: rescanned after an audio add or removal, and the only library the music sync follows new albums from (0 = both off). Jellyfin setups leave it at 0
scheduler.music_sync	Sunday 15:00	Weekly music sync slot (config.json only: the Sync Scheduler card has no music row)
music_discovery.new_releases.enabled	true	Follow the new albums of the artists in Tiramisu's music library
music_discovery.new_releases.window_days	30	How recent an album's first edition must be to count as new
music_discovery.new_artists.enabled	true	Import recent albums of new artists whose nearest artists you own
music_discovery.new_artists.window_days	30	How far back the fresh-releases feed is read (at most 90)
music_discovery.new_artists.debut_years	3	An artist counts as new when its first album or EP is at most this old (0 = any age)
music_discovery.max_albums_per_run	20	Cap shared by the new-artist, genre and similar-artist passes (new albums of your own artists are uncapped)
music_discovery.seeds_recency_days	[1, 7, 30, 60]	Age tiers of the plays that pick your seed artists: a play weighs 1 in the first tier and half as much in each next one; older plays do not count, and with no plays in the last tier the genre and similar-artist passes find nothing
music_discovery.seeds_min_plays	3	Plays an artist needs inside the tiers to become a seed
music_discovery.genres.enabled	true	Import niche artists of the genres you listen to now, close to your artists
music_discovery.genres.count	8	How many of your genres are explored
music_discovery.genres.debut_years	15	An artist of the genre pass counts as new when its first album or EP is at most this old (0 = any age)
music_discovery.similar.min_fans	10000	Similar artists with fewer Deezer fans are too obscure to suggest (0 = no floor)
music_discovery.similar.max_fans	100000	Similar artists with more Deezer fans are too known to suggest (0 = no limit)
music_discovery.similar.debut_years	15	A similar artist's first album or EP must be at most this old (0 = any age)
tmdb_api_key	(none)	TMDB API key
prowlarr.enabled	false	Use Prowlarr as primary indexer (falls back to Torrentio if disabled)
prowlarr.api_key	(none)	Prowlarr API key (Settings → General → API Key)
prowlarr.url	(none)	Prowlarr base URL (e.g. http://192.168.1.x:9696)
natpmp.enabled	false	Enable NAT-PMP
natpmp.gateway	(none)	VPN gateway IP
natpmp.vpn_interface	wg0	WireGuard interface

Quality Scoring

Every candidate release, film or episode, is scored before it is chosen:
resolution, HDR and Dolby Vision, the audio track, remux, your preferred
language, the seeder count and the size gates all add up to a single number, and
the highest one wins. Those weights used to be fixed in the code; they now live
in an optional quality_scoring block in config.json, editable live from the
Release Selection card in the Control Panel.

Omitting the block keeps the shipped defaults, so an existing install changes
nothing until you add it deliberately. movies and tv are independent: you
can set one without the other, and any field you leave out falls back to that
profile's default.

{
  "quality_scoring": {
    "movies": {
      "res_4k": 1000,
      "res_1080p": 200,
      "hdr": 60,
      "dolby_vision": 100,
      "atmos": 50,
      "audio_5_1": 25,
      "stereo_penalty": -50,
      "remux": 30,
      "preferred_language": 60,
      "unknown_size_4k_penalty": -5,
      "seeder_cap": 50,
      "min_seeders": 15,
      "min_4k_gb": 10,
      "max_4k_gb": 40,
      "min_1080p_gb": 4,
      "max_1080p_gb": 20
    },
    "tv": {
      "res_4k": 1000,
      "res_1080p": 200,
      "hdr": 100,
      "dolby_vision": 150,
      "atmos": 50,
      "audio_5_1": 25,
      "preferred_language": 40,
      "fullpack": 500,
      "seeder_tier_100": 100,
      "seeder_tier_50": 50,
      "seeder_tier_20": 10,
      "min_seeders": 5,
      "min_seeders_4k": 5,
      "season_skip_score": 1000
    }
  }
}

The Release Selection card ships four presets that fill both profiles at
once and then let you fine-tune single fields:

• Best Quality (default): the values above; resolution, HDR and Atmos weigh
  the most, and both syncs use this scale unless you pick another preset.
• 1080p: for setups that should stop treating 4K as automatically better, a
  NAS that cannot transcode it for instance: res_1080p outweighs res_4k.
• Fast Swarms: favors releases with more seeders over marginal quality gains,
  for when cold starts matter more than a Dolby Vision bump.
• Max Quality: pushes resolution, HDR, Atmos and remux higher and tightens
  the seeder floor, for a library where quality always wins.

Language

Release-name language signals, used by the scoring and by the rejection gates:

"language": {
  "preferred_terms": ["ita", "multi", "dual"],
  "preferred_flags": ["IT"],
  "excluded_flags": ["ES", "FR", "DE", "RU", "CN", "JP", "KR", "TH", "PT", "BR",
                     "UA", "PL", "NL", "TR", "SA", "IN", "CZ", "HU", "RO"]
}

preferred_terms are case-insensitive, word-boundary-matched release-name terms
(e.g. ita, multi, dual); preferred_flags and excluded_flags are ISO
3166-1 alpha-2 codes matched against the flag emoji in indexer result lines. The
block is optional, and omitting it keeps these defaults.

Runtime Environment Variables

Environment="GOMEMLIMIT=2200MiB"
Environment="GOGC=100"

GOMEMLIMIT=2200MiB leaves headroom for OS and Samba on a 4 GB Pi 4.

---

Sync Engine (Go Native)

All sync logic runs natively inside the Go binary. No Python, no external scripts, no subprocess overhead. Configure schedules from the Control Panel at :9080/control → Sync Scheduler.

Movies Sync

Queries TMDB Discover + Popular (Italian + English, region IT+US), evaluates Prowlarr/Torrentio results, adds the best torrent.

Trigger from Control Panel → Sync Scheduler → Movies → "Run now", or via API:

curl -X POST http://127.0.0.1:9080/api/scheduler/movies/run

• Quality: 4K DV > 4K HDR10+ > 4K HDR > 4K > 1080p REMUX > 1080p
• Min seeders: 15 · Min size: 10 GB (4K), 4 GB (1080p)
• Skips existing films (by TMDB ID) · Upgrades lower-quality entries

TV Sync

curl -X POST http://127.0.0.1:9080/api/scheduler/tv/run

Fullpack-first approach, prefers complete season packs. Plex/Jellyfin-compatible directory structure:

Show Name (Year)/
  Season.01/
    Show_Name_S01E01_<hash8>.mkv
    Show_Name_S01E02_<hash8>.mkv

Dead-Release Reaper

A torrent can die without anyone noticing: the release stays in the library, but
its swarm stops answering. The engine counts the metadata timeouts of each
release, and when a title crosses the threshold it is re-searched in later syncs
instead of being left as a file that can never play.

On movies the dead release is skipped, the title is looked up again even outside
the usual discovery window, and either a live release replaces it or the stub is
removed. On TV the decision is per pack, because one season pack stands behind
up to twenty episodes: the pack is removed only when every season it covers was
searched end to end, and an episode that simply could not be checked is kept
rather than guessed away. Every episode removed this way is also recorded as a
hole, so a show the discovery feed no longer returns can still be repaired later
(see Episode gaps in the Library API).

Watchlist Sync

curl -X POST http://127.0.0.1:9080/api/scheduler/watchlist/run

Reads Plex cloud watchlist → IMDB ID resolution → Prowlarr/Torrentio (min 15 seeders, the movie profile) → GoStorm.

Music Sync

curl -X POST http://127.0.0.1:9080/api/scheduler/music/run

Weekly, Sunday 15:00 by default (scheduler.music_sync). Every album is filed
through the Library API as FLAC projections, one per track. Three passes:

• New albums of your artists. Every artist of Tiramisu's music library with a
  MusicBrainz id is followed: albums and EPs whose first edition came out in the
  last window_days (30) and that the library lacks are imported, with no cap.
  Live, compilation and remix groups, reissues, undated and future releases never
  qualify. An album with no torrent yet is retried on every run while it stays in
  the window. MusicBrainz is asked in batches of 40 artists, so 800 artists cost
  about 20 requests.
• New artists close to yours. The sitewide ListenBrainz fresh-releases feed is
  filtered down to artists you do not have whose nearest artists on ListenBrainz
  include yours, and whose first album or EP is at most debut_years (3) old;
  more of your artists among the neighbours ranks higher. Only about a third of new
  artists have similarity data yet, so expect a handful a month. The first run
  looks up every artist of the window (about an hour for 30 days); the answers are
  cached in the discovery state for 30 days, so later runs look up only the week's
  new names.
• Niche artists of your genres (Plex only). The genres of your seed artists
  (below) pick the pools: the least played recordings of each genre on ListenBrainz,
  resolved to artists you do not have. An artist is kept when one of your artists is
  among its nearest neighbours and its first album or EP is at most debut_years
  (15) old; one of your seeds among the neighbours ranks it highest. Its latest
  studio album already released is imported.
• Similar artists (Plex only). The Deezer related artists of your seed artists
  (public endpoints, no key), pooled and ranked by how many of your seeds point at
  them. Artists any library already holds, artists outside min_fans-max_fans
  (10,000-100,000) Deezer fans and artists whose first album or EP is older than
  debut_years (15) are dropped; the latest studio album comes from MusicBrainz.

The seeds come from the Plex server owner's plays of the last 60 days (the users the
server is shared with do not count), weighted by age: a play of
the last day counts 1, of the last week 0.5, of the last month 0.25, of the last two
months 0.125. With no plays in 60 days the genre and similar-artist passes find
nothing.

The last three passes share max_albums_per_run (20), in order new artists, genres,
similar artists, one album per artist.

The new-album pass reads only Tiramisu's own music library, for the artists and
for the duplicate check: on Plex the section in plex.music_library_id (0 turns
the pass off), on Jellyfin the music library that holds the albums Tiramisu filed.
Jellyfin keeps no play history, so there the genre and similar-artist passes are
skipped and the other two run. It reads /Library/VirtualFolders and /Items with the Authorization: MediaBrowser
header, which Jellyfin 10.x and 12.x both accept, and needs MusicBrainz ids on the
albums (tagged files, or the bundled MusicBrainz metadata provider).

---

Library API (:9080)

The HTTP way to add or remove a title, for clients that cannot touch the
filesystem: an AI agent, a script on another machine, or simply curl. One
request does what the sync engine does for a single release: it registers the
torrent, waits for the file list, picks the video file, writes the virtual
.mkv with the same naming convention, registers TV episodes in the state DB,
and asks the media server to rescan.

# Add a movie. release_title is the raw release name: the quality tags in the
# filename (_DV, _Atmos, _REMUX) are read from it.
curl -s -X POST -H 'Content-Type: application/json' --max-time 120 \
  -d '{"type":"movie","hash":"<infohash>","title":"Dummy Bunny","year":2024,
       "release_title":"Dummy.Bunny.2024.2160p.UHD.BluRay.REMUX.DV.Atmos-GRP",
       "imdb":"tt1234567"}' \
  http://127.0.0.1:9080/api/library/add

# Add one episode, or a whole season pack by leaving "episode" out
curl -s -X POST -H 'Content-Type: application/json' --max-time 120 \
  -d '{"type":"tv","hash":"<infohash>","title":"Dummy Bunny","first_air_date":"2015-06-24",
       "season":1,"episode":2,"release_title":"Dummy.Bunny.S01E02.1080p"}' \
  http://127.0.0.1:9080/api/library/add

add answers 201 with the path, fuse_path and declared size of every stub
it wrote, or 200 with "already_present": true when the release was already
filed. A season pack is never short-circuited that way, because which episodes
it contains is only known once the file list arrives; re-adding one rewrites the
episodes it names and replaces the releases they came from. Failures follow the
same rule as the sync: every error removes the torrent it added, so a failed
call leaves nothing behind.

For TV, first_air_date puts the year in the series folder, and quality_score
is what the next sync compares against before replacing the episode. imdb is
written into movie stubs only; episode stubs carry no id, the same convention
the sync follows. magnet can replace hash; is_4k, file_index and
quality_score override what would otherwise be inferred, and metadata_wait
(default 60 seconds, capped at 300) is how long the call waits for the swarm to
answer, so keep the client timeout above it.

Errors say which half broke: 400 the request, 422 the torrent holds no video
file, 502 the engine refused it, 503 the state DB is unavailable, 504 no
metadata in time. Every failure removes the torrent it added, so a failed call
leaves nothing behind.

# What the library already holds, one entry per stub. type is a filter: movie
# lists the movie library, tv the series one, gaps the open holes. Any other
# value silently falls back to the movie list, so a typo reads as a wrong answer.
curl -s 'http://127.0.0.1:9080/api/library/list?type=movie' | jq '.[] | {fuse_path, size, hash, imdb}'
curl -s 'http://127.0.0.1:9080/api/library/list?type=tv'    | jq '.[] | {fuse_path, season, episode}'

# Remove. blacklist:true records the release the way the FUSE unlink handler
# does, so the sync will not add the title back.
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"path":"movies/Dummy_Bunny_2024_2160p_DV_Atmos_REMUX_e7f8a9b0.mkv","blacklist":true}' \
  http://127.0.0.1:9080/api/library/remove

Removing a stub drops its torrent only when no other stub still points at it:
one season pack is a single torrent behind many episodes.

Music and audiobooks (v1.10.0)

music/ and audiobooks/ use the same endpoints with their own rules. The caller
supplies the final path and Tiramisu validates what the engine owns: section
containment, extension agreement, the mandatory _<hash8> suffix (the last eight
hex digits of the infohash, before the extension) and collision rules. Music admits
.flac only; audiobooks admit .m4b, .m4a and .mp3.

# 1. Inspect hydrates the magnet and returns the file list. The engine adds the
# torrent itself, so a magnet is enough; metadata_wait works as in add.
curl -s -X POST -H 'Content-Type: application/json' --max-time 300 \
  -d '{"magnet":"magnet:?xt=urn:btih:...","title":"Dummy Album"}' \
  http://127.0.0.1:9080/api/library/inspect

# 2. Add an album, one projection per file. external_id is the caller's identity
# (a MusicBrainz release group, an ASIN) and external_id_ns its namespace: it is
# stored verbatim, written into the stub, and returned by list.
curl -s -X POST -H 'Content-Type: application/json' --max-time 300 \
  -d '{"type":"music","hash":"<infohash>","title":"Dummy Album",
       "files":[{"source_path":"Release/01 - One.flac",
                 "path":"Artist/Album/01 - One_e7f8a9b0.flac",
                 "external_id":"<release-group-mbid>","external_id_ns":"musicbrainz"}]}' \
  http://127.0.0.1:9080/api/library/add

# 3. List pages instead of returning an array, and shows the identity per row.
# prefix filters the section; failures=1 adds the reachability counters.
curl -s 'http://127.0.0.1:9080/api/library/list?type=music&limit=200' | \
  jq '{next_cursor, items: [.items[] | {path, external_id, external_id_ns}]}'
curl -s 'http://127.0.0.1:9080/api/library/list?type=music&prefix=Artist/Album&failures=1'

# 4. Remove one projection by exact path, or a whole album by prefix.
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"type":"music","path":"Artist/Album/01 - One_e7f8a9b0.flac"}' \
  http://127.0.0.1:9080/api/library/remove
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"type":"music","prefix":"Artist/Album"}' \
  http://127.0.0.1:9080/api/library/remove

add answers 201 for the projections it created, or 200 with
"already_present": true when they are already filed. On a replay the stored
identity wins and a disagreement is logged, so changing an identity means removing
and adding again. remove is idempotent: an absent path answers removed: false
with state: "absent". Prefix removal takes a whole album in one call and answers
409 when the rows under it do not share exactly one torrent, which is the engine
saying that directory is not an album. blacklist is not audio lifecycle state and
is rejected. Hash-wide, directory and batch removal remain out of Phase 1. A
torrent is never dropped while another projection still references it.

Projections are read-only to their clients: files answer 0444, directories
0555, and the mutations a scanner never needs (write open, truncate, rename,
mkdir, chmod) are refused with EROFS, while a direct unlink gets EPERM. Adding,
re-filing and removing happen only through the API.

Two things worth knowing before scripting against it. The type must be exactly
music or audiobook: list keeps the legacy fallback for unknown values, so the
plural audiobooks answers 200 with the movie library instead of an error. And a
music add or removal asks the media server to rescan the section in
plex.music_library_id (Jellyfin refreshes every library, audiobooks included).
On Plex, audiobooks have no library id yet, so the audiobooks/ section is scanned
manually, once, when the batch is done.

Episode gaps (v1.9.71)

When the TV reaper removes an episode whose release died, it does not just
delete the stub: it records the hole, so a show the discovery feed no longer
returns can still be repaired later. type=gaps lists those holes, oldest
first.

curl -s -D- 'http://127.0.0.1:9080/api/library/list?type=gaps' | \
  jq '.[] | {episode_key, show, season, path, dead_hash, removed_at, last_attempt}'

last_attempt is when the repair pass last re-searched the hole, and it stays
0 when it never has, which is why it carries no omitempty: 0 means "never
tried", not "tried at epoch". The listing is capped at 500 entries and the true
count travels in the X-Total-Count header, so a client reading a full page can
tell it is not the whole backlog.

The TV sync repairs gaps on its own: one search per affected season, at most 5
shows per run, and no sooner than 6 hours after the last attempt on the same
hole. Filing the episode yourself with /api/library/add closes its gap too: a
gap is cleared whenever the episode has a live release again, whoever put it
there.

[!WARNING]
Nothing on :9080 is authenticated. /api/config returns the whole
configuration, keys and tokens included, and accepts a POST that rewrites it;
/api/library/add and /api/library/remove write and delete files in the
library. Keep the port on a trusted network, or behind a reverse proxy that
requires authentication.

---

MCP Server

Tiramisu serves its library tools over MCP at http://<host>:9080/mcp
(Streamable HTTP). An agent searches releases with the deployment's own scoring
profile, the same pipeline the sync uses, files the one you pick, lists and
removes entries:

• Claude Code: claude mcp add --transport http tiramisu http://<host>:9080/mcp
• Any MCP client that speaks Streamable HTTP: point it at the same URL.

Tool	What it does
resolve_title	Title → IMDb id (and TMDB id, first-air date for shows)
search_releases	Prowlarr + Torrentio search, gated and scored like the sync; returns a job
get_job	Polls a search, add or inspect job
add_release	Files the candidate you chose; TV releases are checked against the show's names
resolve_album	Artist → discography from MusicBrainz, or one album; flags what is already in the library
search_album, add_album	The music sync's own search (lossless only) and filing: MusicBrainz track ids, cue images split per track
inspect_torrent, add_audio	A torrent you name, and audiobooks: list its files, file its tracks
list_library, list_gaps	What the library holds; TV episodes the reaper removed
remove_entries	Preview first; removes only with confirm, for good or to replace

Searches and adds run as jobs: indexer searches can take minutes. The agent
always asks before adding or removing. It changes the scoring profile only for
one search and only when you ask, and never writes it to config.json.

add the latest Dummy Bunny movie in 4K
add Dummy Bunny's discography
season 2 of Dummy Bunny is missing episodes 4 to 8, fill them in
is Dummy Bunny (2024) already in the library, and in what quality?

The search tools need v1.12.0 or later.

Trust model: like the rest of :9080, /mcp has no authentication.
Keep the port on your LAN.

---

Plex/Jellyfin and Samba Setup

Connecting a Media Server

Point the Media Server card in the Control Panel at your server, and Tiramisu
identifies which product answers, showing it as verified with its latency. It
also broadcasts on the LAN, Plex GDM on UDP 32414 and Jellyfin on UDP 7359, and
lists whatever replies, so a server on the same network appears without
configuration. A broadcast does not cross a Docker bridge network, and Jellyfin
lets you switch its discovery off, so setting the URL is the reliable way.

Setting	Plex	Jellyfin
media_server_type	plex	jellyfin
plex.url	http://host:32400	http://host:8096
plex.token	X-Plex-Token	API key: Dashboard → Advanced → API Keys → +
plex.library_id / plex.tv_library_id	Section IDs to refresh after a sync	Leave at 0

The token drives the library refresh Tiramisu issues when the movies, TV and
watchlist syncs finish, and the field names keep the plex. prefix for backward
compatibility: they hold whichever server media_server_type names. Plex
refreshes the section named by library_id and does nothing without one;
Jellyfin refreshes every library, which is why its section IDs stay at 0.
Without a token the media server finds new files on its own scan schedule
instead. The playback sessions and posters on the dashboard are Plex-only.

Samba Configuration

Critical parameters in /etc/samba/smb.conf to prevent FUSE deadlocks during Plex/Jellyfin library scans:

[tiramisu-mkv-virtual]
   path = /mnt/tiramisu-mkv-virtual
   browseable = yes
   read only = yes
   oplocks = no           # CRITICAL: prevents kernel exclusive locks on FUSE files
   aio read size = 1      # CRITICAL: forces async I/O, prevents smbd D-state
   deadtime = 15          # cleans inactive SMB connections every 15 minutes
   vfs objects = fileid   # CRITICAL: transmits 64-bit inodes to Synology/Plex/Jellyfin

[!WARNING]
oplocks = no is non-negotiable. With oplocks enabled, the kernel requests exclusive locks on FUSE-backed files, causing smbd threads to enter D-state indefinitely during concurrent Plex/Jellyfin scans.

[!IMPORTANT]
vfs objects = fileid ensures 64-bit inode transmission. Without it, Synology receives truncated 32-bit inodes, causing Plex to misidentify files.

Synology CIFS Mount

Source:  //pi-ip/tiramisu-mkv-virtual
Target:  /volume1/Tiramisu
Options: serverino,vers=3.0,uid=1024,gid=100,file_mode=0777,dir_mode=0777

serverino must remain active. Synology may silently drop it after network timeouts. Schedule a Task Scheduler job (every 5 min) to verify and remount if needed.

---

Build from Source

[!IMPORTANT]
Compile natively on the target machine. Do not cross-compile: the PGO profile must match the target CPU architecture.

ssh [email protected]
cd ~/Tiramisu

/usr/local/go/bin/go clean -cache
/usr/local/go/bin/go mod tidy
GOARCH=arm64 CGO_ENABLED=1 /usr/local/go/bin/go build -pgo=auto -o tiramisu .

# Deploy: the install directory is ~/Tiramisu by default; if you built
# elsewhere, copy the binary there first
sudo systemctl stop tiramisu
sudo systemctl start tiramisu

Verify the toolchain is 64-bit:

/usr/local/go/bin/go version
# Required: go version go1.26.x linux/arm64
# Wrong:    go version go1.26.x linux/arm   <-- 32-bit

Install Go 1.26 if needed:

wget https://go.dev/dl/go1.26.8.linux-arm64.tar.gz
sudo tar -C /usr/local -xzf go1.26.8.linux-arm64.tar.gz

---

Docker

[!IMPORTANT]
Tiramisu mounts a FUSE filesystem at startup. Docker blocks this syscall by default. The container requires elevated privileges to run.

Pre-built images for linux/amd64 and linux/arm64 are published automatically on every release to Docker Hub and GitHub Container Registry:

Registry	Image
Docker Hub	mrrobotogit/tiramisu:latest
GHCR	ghcr.io/mrrobotogit/tiramisu:latest

Pull:

docker pull mrrobotogit/tiramisu:latest
# or
docker pull ghcr.io/mrrobotogit/tiramisu:latest

Run:

docker run -d \
  --name tiramisu \
  --restart unless-stopped \
  --device /dev/fuse \
  --cap-add SYS_ADMIN \
  --cap-add NET_ADMIN \
  -v /path/to/config.json:/config.json \
  -v /path/to/state:/state \
  -v /mnt/tiramisu-mkv-real:/mnt/tiramisu-mkv-real \
  -v /mnt/tiramisu-mkv-virtual:/mnt/tiramisu-mkv-virtual:rshared \
  -p 8090:8090 \
  -p 9080:9080 \
  mrrobotogit/tiramisu:latest

Or use --privileged as a simpler alternative to the individual capabilities (e.g. on a Raspberry Pi where the container is fully trusted). In practice --cap-add SYS_ADMIN/NET_ADMIN alone have been reported insufficient on some Ubuntu hosts — if the container starts cleanly but the virtual directory stays empty, use --privileged.

config.json must be volume-mounted at /config.json (the default MKV_PROXY_CONFIG_PATH). Use config.json.example as the starting point. Do not mount it :ro: the Control Panel writes settings back to this file, and a read-only mount makes every save fail.

Mount a volume on /state. Everything that must outlive the container lives there:

Path	Holds
/state/config.db	Torrent list, and GoStorm settings when StoreSettingsInJson is off
/state/settings.json	GoStorm settings: peer port, cache size, connection limit
/state/STATE/	Inode map and sync caches
/state/logs/	Log files the Control Panel tails
/state/blocklist	The downloaded IP blocklist

Mount a host directory there and everything survives docker rm. Without that volume the peer port, the torrent list and every other setting are discarded when the container is removed, and the next docker run starts from the defaults; the container prints a warning on startup when it detects this. /state is the default, so TIRAMISU_ROOT_PATH only needs setting to move the whole directory elsewhere, and TIRAMISU_STATE_DIR / TIRAMISU_LOG_DIR default to STATE/ and logs/ underneath it.

Do not mount a named or anonymous Docker volume expecting the warning to catch a mistake: an anonymous volume looks mounted, but a fresh docker run attaches a new empty one. Use a host path.

Updating the container. Unmount the virtual directory between removing the old container and starting the new one: Docker refuses to bind-mount over the FUSE mount the previous container left behind.

docker pull mrrobotogit/tiramisu:latest
docker rm -f tiramisu
sudo fusermount3 -uz /mnt/tiramisu-mkv-virtual
docker run -d ...   # same flags as above

[!TIP]
Troubleshooting: real directory fills up, virtual stays empty. If docker logs shows FUSE mounted at ... all systems active and the InodeMap saving files, but /mnt/tiramisu-mkv-virtual is empty on the host, the FUSE mount succeeded inside the container but never propagated out — Docker bind mounts default to private propagation, so a mount created inside the container isn't visible outside it. Fix: add :rshared to the virtual volume's -v flag (as above). If Docker then refuses to start with an error like "must be shared or slave", the host mountpoint itself isn't shared yet - run sudo mount --make-rshared /mnt (or whichever parent directory holds it) once, then restart the container.

Build from source (from the repository root):

docker build -f docker/Dockerfile -t tiramisu .

Windows Docker Installer

For Windows users, a dedicated installer generates a ready-to-use Dockge stack with Tiramisu + Plex or Jellyfin in a single container:

👉 docker-windows/

• Run docker-windows\install-rebuild.bat for interactive setup (flavor, paths, ports)
• Auto port conflict resolution
• Idempotent rebuild: never deletes existing media or config data

Requires: Docker Desktop with WSL2 (Linux containers) and FUSE support (/dev/fuse available inside containers).

---

API Quick Reference

Two JSON APIs, one per layer: the GoStorm engine at :8090 manages torrents and
settings, the Tiramisu side at :9080 exposes metrics (and the Library API, in
its own section above). Handy for scripts, and for checking what is happening
without opening the web UI.

GoStorm API (:8090)

# List all torrents (count)
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"action":"list"}' http://127.0.0.1:8090/torrents | jq length

# Add a torrent
curl -X POST -H 'Content-Type: application/json' \
  -d '{"action":"add","link":"magnet:?xt=urn:btih:...","title":"Film Title (Year)"}' \
  http://127.0.0.1:8090/torrents

# Active torrents (in RAM, not DB)
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"action":"active"}' http://127.0.0.1:8090/torrents | \
  jq '.[] | {title: .title[:50], speed_mbps: ((.download_speed//0)/1048576|round), peers: (.active_peers//0)}'

# Read settings
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"action":"get"}' http://127.0.0.1:8090/settings | jq

# Remove a torrent
curl -X POST -H 'Content-Type: application/json' \
  -d '{"action":"rem","hash":"<infohash>"}' http://127.0.0.1:8090/torrents

The engine also accepts drop (unload from RAM, keep it in the DB) and wipe
(remove every torrent, rarely what you want).

Removing a title means removing its stub, not just its torrent. Two ways do it
properly, and deleting the stub from the source directory is neither: that
leaves the torrent registered and records nothing, so the next sync brings the
title back.

# through the Library API, with the same effect as the unlink below
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"path":"movies/<file>.mkv","blacklist":true}' \
  http://127.0.0.1:9080/api/library/remove

# or through the FUSE mount: the unlink handler closes open handles, removes the
# torrent from the engine and blacklists it
rm /mnt/tiramisu-mkv-virtual/movies/<file>.mkv

Tiramisu API (:9080)

# Key metrics fields
curl -s http://127.0.0.1:9080/metrics | \
  jq '{version, uptime, read_ahead_active_bytes, config_source}'

# Playback quality: time to first byte, stalls, seek latency
curl -s http://127.0.0.1:9080/metrics/ttff | jq

# Blocklist status
curl -s http://127.0.0.1:9080/metrics/blocklist | jq

# Health check and scheduler state
curl -s http://127.0.0.1:9080/api/health | jq
curl -s http://127.0.0.1:9080/api/scheduler/status | jq

# Search indexers by IMDB id, using the Prowlarr credentials from the config.
# Queries Prowlarr only: the sync engine also queries Torrentio and merges.
# An empty array means Prowlarr is not configured, not that nothing was found.
curl -s "http://127.0.0.1:9080/api/prowlarr/search?imdb_id=tt0088196&type=movie&year=1985" | jq

# Running configuration, including the quality_scoring profile in use
curl -s http://127.0.0.1:9080/api/config | jq '.quality_scoring'

---

FAQ

What is Tiramisu?
Tiramisu is a self-hosted BitTorrent engine with a built-in FUSE virtual filesystem. It presents torrents as normal, seekable .mkv files to Plex or Jellyfin, and streams the bytes live from the swarm as they are read, with no download step and no temp files.

How is this different from Real-Debrid or other debrid services?
Debrid services are third-party paid subscriptions that cache torrents on someone else's servers and hand you an HTTP link. Tiramisu runs entirely on hardware you own, no subscription, no third-party server, no monthly fee. You get the same "instant playback" experience, but the BitTorrent swarm itself is the source, not a rented cache.

Does Tiramisu store or download the files?
No persistent copy of the media is kept. Byte ranges pass through RAM (and an optional bounded SSD cache limited to the first/last few MB of each file, purely to speed up the first seconds of playback) and are never written to disk as complete files. There is no storage quota to plan around because there is nothing to store.

Do I need to seed or keep uploading?
Tiramisu participates in the swarm like any BitTorrent client while a file is open, but retention drops automatically once playback stops, and no long-term seeding is required or expected.

What hardware do I need?
A Raspberry Pi 4 (4 GB RAM) is the tested minimum baseline, and it comfortably handles 4K HDR streaming. Any linux/amd64 or linux/arm64 machine works: NAS, VPS, mini-PC, or any always-on Linux box.

*Does it work with Sonarr, Radarr, or other Arr tools?
Not directly. Tiramisu has its own built-in sync engine that talks to TMDB, Prowlarr, and Torrentio to discover and add titles automatically, so it does not need the *Arr suite to function. There is currently no compatibility layer for those tools specifically.

Is this legal?
Tiramisu is a general-purpose BitTorrent engine and streaming filesystem. It does not host, index, or distribute any copyrighted content itself; what you do with it is your responsibility, same as with any BitTorrent client.

Is my data private?
Everything runs on your own hardware. No account, no third-party API key is required for the core engine to work (TMDB, Prowlarr, and Plex/Jellyfin integrations are optional and use your own credentials).

---

Troubleshooting

Plex shows buffering or "Playback Error"

Check warmup cache:

curl -s http://127.0.0.1:9080/metrics | jq '.read_ahead_active_bytes'

If empty, force a Plex/Jellyfin library scan. The scan reads the first MB of each file and populates the SSD head warmup.

Check active torrent status:

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"action":"active"}' http://127.0.0.1:8090/torrents | \
  jq '.[] | {title: .title[:50], speed_mbps: ((.download_speed//0)/1048576|round), peers: (.active_peers//0)}'

If peer count < 3 and you are routing through WireGuard, check NAT-PMP configuration.

smbd D-state or Samba hangs during Plex/Jellyfin scan

Almost always one of three causes:

1. oplocks = no missing from smb.conf: kernel acquires exclusive locks on FUSE files, smbd blocks indefinitely
2. vfs objects = fileid missing: Synology receives truncated 32-bit inodes
3. serverino dropped on Synology CIFS mount: check with mount | grep tiramisu

Check for D-state processes:

ps aux | grep -E 'smbd|tiramisu|fuse' | awk '$8 == "D"'

Few seeders or slow downloads

If you are routing BitTorrent traffic through WireGuard, enable NAT-PMP to restore inbound port reachability through the VPN gateway:

"natpmp": {
  "enabled": true,
  "gateway": "10.2.0.1",
  "vpn_interface": "wg0"
}

Without an open inbound port, peers cannot initiate connections: the engine
relies solely on outbound ones.

If you are not using a VPN, forward the peer port on your router. Tiramisu
asks the router for the mapping over UPnP on its own, but many routers ship with
UPnP disabled (and some ISP routers do not offer it at all). When that request
fails nothing is logged as an error: the port simply stays closed and peer
counts stay low.

1. Pin the port. In the Control Panel, set GoStorm → PeersListenPort to a
   fixed high port (e.g. 64407). Left at 0 the engine picks a new random port
   on every start, which no static forward can follow.
2. Forward that same port to the machine running Tiramisu, both TCP and UDP.
3. Verify from outside your network that the port is open: a closed port and a
   working UPnP mapping look identical from the inside.

A router that drops the unforwarded traffic and logs every drop can also wear
out its own flash storage over time; if your router has a firewall logging
option, check it is not writing a line per dropped packet.

Service fails to start

sudo systemctl status tiramisu
tail -30 /home/pi/logs/tiramisu.log

If the FUSE mount is stale:

fusermount3 -uz /mnt/tiramisu-mkv-virtual
sudo systemctl start tiramisu

Ensure mount point exists:

sudo mkdir -p /mnt/tiramisu-mkv-virtual
sudo chown pi:pi /mnt/tiramisu-mkv-virtual

Webhook not triggering Priority Mode (Plex or Jellyfin)

Verify connectivity:

curl -v http://127.0.0.1:9080/plex/webhook \
  -X POST -H 'Content-Type: application/json' \
  -d '{"event":"media.play","Metadata":{"librarySectionType":"movie","guid":"imdb://tt1234567","Guid":[{"id":"imdb://tt1234567"}]}}'

Check logs:

grep -i webhook /home/pi/logs/tiramisu.log | tail -20

If the connection appears in logs but IMDB matching fails, verify the raw payload contains imdb://tt\d+. Tiramisu uses regex on the raw JSON string, so it works even with localized titles.

Jellyfin-specific: if you see no log entry at all, confirm the Content-Type header is set correctly (Key: Content-Type, Value: application/json). Jellyfin does not send the request when the Content-Type override is malformed.

High CPU usage

Profile the live binary:

go tool pprof -top "http://127.0.0.1:9080/debug/pprof/profile?seconds=30"

Expected hot paths: sha1.blockGeneric (no crypto extensions on Pi 4 A72), io.ReadFull, sync.(*Mutex).Lock. Regenerating the PGO profile typically reduces CPU 5–7%.

---

Key File Locations

Paths below use the defaults set by install.sh. All are configurable during installation.

Runtime (install directory, default ~/Tiramisu/)

Path	Purpose
~/Tiramisu/tiramisu	Production binary
~/Tiramisu/config.json	Live configuration (edit → sudo systemctl restart tiramisu)
~/Tiramisu/STATE/tiramisu.db	SQLite state database: inode map, sync caches, episode registry, scheduler state
~/Tiramisu/logs/	All service logs (tiramisu.log, movies-sync.log, tv-sync.log, watchlist-sync.log)
/mnt/tiramisu-mkv-virtual/	FUSE mount point (served to Plex/Jellyfin -> Samba)
/etc/systemd/system/tiramisu.service	systemd service definition

Build (cloned repository)

Path	Purpose
~/Tiramisu/	Install directory: clone, build and runtime
~/Tiramisu/default.pgo	PGO profile, regenerate after major code changes

---

Support

Tiramisu is free and open source. If it's saving you a monthly chip, consider fueling the engine!

---

License

GNU General Public License v3.0