Sonarr / Radarr

AIOStreams can act as a SABnzbd download client for Sonarr and Radarr. They grab NZBs as usual, but nothing is downloaded: AIOStreams inspects the release, exposes it as a file, and the arr imports a symlink into your library. Plex, Jellyfin or Emby then play it, and the bytes are streamed from Usenet on demand.

What you get out of it:

• A library that costs no disk space and appears the moment a grab is verified.
• The arr's own automation intact — profiles, upgrades, renaming, monitoring.
• A library recheck that notices when a release is taken down later, and asks the arr for a replacement.

Before you start

You need three things already working. This guide only connects them.

1. The built-in Usenet engine, with at least one provider — Settings → Usenet.
2. Sonarr or Radarr set up as normal, with indexers and a quality profile — Sonarr quick start, Radarr quick start. AIOStreams replaces the download client, nothing else.
3. A Linux host, if you want AIOStreams to do the mounting itself. Otherwise any platform that can run rclone.

How the pieces fit

Sonarr/Radarr ──grab──▶ AIOStreams (SABnzbd API) ──▶ inspects the NZB
      │                                                     │
      │                                            exposes it as files
      │                                                     ▼
      └──imports a symlink from──▶   the mount   ◀── FUSE / NFS / rclone
                                         │
                           Plex/Jellyfin read the symlink,
                        AIOStreams streams the bytes on demand

Three things have to agree:

1. The arr talks to AIOStreams over the SABnzbd API.
2. The library is mounted as a real filesystem somewhere — the arrs cannot import from a URL.
3. Everyone sees that mount at the same absolute path — the arr, AIOStreams and your media server. This is the step that goes wrong.

Setting it up

AIOSTREAMS_AUTH=arr:a-long-random-password

mount -t nfs4 -o vers=4.0,ro aiostreams:/ /mnt/aiostreams

rclone config create aiostreams webdav \
  url=https://your-aiostreams-instance/webdav \
  vendor=other \
  user=arr \
  pass="$(rclone obscure a-long-random-password)"

rclone mount aiostreams: /mnt/aiostreams \
  --links \
  --read-only \
  --dir-cache-time 20s \
  --vfs-cache-mode off \
  --allow-other

A full Docker setup

Starting from nothing, these are complete working stacks: AIOStreams, Sonarr and a media server sharing one mount. Pick the one matching the mount you chose above.

services:
  aiostreams:
    image: ghcr.io/viren070/aiostreams:latest
    container_name: aiostreams
    environment:
      - SECRET_KEY=${SECRET_KEY} # openssl rand -hex 32
      - BASE_URL=https://aiostreams.example.com
      - AIOSTREAMS_AUTH=arr:${ARR_PASSWORD}
    volumes:
      - ./aiostreams:/app/data
      # rshared is what makes the mount visible to the other containers
      - /mnt:/mnt:rshared
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse:/dev/fuse:rwm
    security_opt:
      - apparmor:unconfined
    ports:
      - 3000:3000
    restart: unless-stopped

  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    container_name: sonarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - ./sonarr:/config
      - /library:/library # where imported episodes go
      - /mnt:/mnt:rslave # the mount, at the same path AIOStreams was told
    ports:
      - 8989:8989
    restart: unless-stopped

  jellyfin:
    image: lscr.io/linuxserver/jellyfin:latest
    container_name: jellyfin
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - ./jellyfin:/config
      - /library:/library
      - /mnt:/mnt:rslave # needed too: it follows the symlinks into the mount
    ports:
      - 8096:8096
    restart: unless-stopped

services:
  aiostreams:
    image: ghcr.io/viren070/aiostreams:latest
    container_name: aiostreams
    environment:
      - SECRET_KEY=${SECRET_KEY} # openssl rand -hex 32
      - BASE_URL=https://aiostreams.example.com
      - AIOSTREAMS_AUTH=arr:${ARR_PASSWORD}
    volumes:
      - ./aiostreams:/app/data
    ports:
      - 3000:3000
    restart: unless-stopped

  rclone:
    image: rclone/rclone:latest
    container_name: rclone
    command: >
      mount aiostreams: /mnt/aiostreams
        --links
        --read-only
        --dir-cache-time 20s
        --vfs-cache-mode off
        --allow-other
        --uid 1000 --gid 1000
    volumes:
      - ./rclone.conf:/config/rclone/rclone.conf
      # rshared is what makes the mount visible to the other containers
      - /mnt:/mnt:rshared
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse:/dev/fuse:rwm
    security_opt:
      - apparmor:unconfined
    depends_on:
      - aiostreams
    restart: unless-stopped

  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    container_name: sonarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - ./sonarr:/config
      - /library:/library # where imported episodes go
      - /mnt:/mnt:rslave # the mount, at the same path AIOStreams was told
    ports:
      - 8989:8989
    restart: unless-stopped

  jellyfin:
    image: lscr.io/linuxserver/jellyfin:latest
    container_name: jellyfin
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - ./jellyfin:/config
      - /library:/library
      - /mnt:/mnt:rslave # needed too: it follows the symlinks into the mount
    ports:
      - 8096:8096
    restart: unless-stopped

[aiostreams]
type = webdav
url = https://aiostreams.example.com/webdav
vendor = other
user = arr
pass = <output of: rclone obscure YOUR_PASSWORD>

The parts that matter, whichever you picked:

• rshared on whichever container owns the mount, rslave on everything else. Without shared mount propagation the other containers see an empty directory where the mount should be. On Docker Desktop (WSL2 backend) only paths under /mnt/wsl accept rshared — use /mnt/wsl/aiostreams:/mnt:rshared there.
• SYS_ADMIN + /dev/fuse are what let anything mount at all.
• Your media server needs the mount too. It follows the symlinks the arr wrote, and the target lives inside /mnt/aiostreams.
• Point the media server's libraries at /library, not at the mount. The arr library scans in seconds and every item is real; the raw content/ tree is laid out as the NZBs were, so a scanner turns a single release with thousands of files into thousands of garbage entries, slowly.

Import modes

Settings → Sonarr / Radarr → Import mode decides what the arr actually imports:

Over rclone the symlink is served as a .rclonelink file and materialised by --links; over FUSE and NFS it is a real symlink. The arrs treat both the same.

What the arr sees

The share has three trees, all read-only. Paths are shown as WebDAV URLs; under a mount they are the same tree from usenet/ down.

When the arr removes a download

Importing a symlink means creating it at the destination and unlinking the source, so the arr deletes files out of completed/ as it goes. AIOStreams treats that as "the arr has taken this file", not "delete the release": the entry disappears from the completed folder and the client's history, but stays under by-id/, so the symlinks already in your library keep working.

Two harmless things you may notice: completed/ lists companion files (.nfo and the like) beside the media — the arrs simply ignore them. And a release with a single file retires its job folder the moment that file is taken, so the arr's follow-up "delete data" logs a directory not found warning; the import has already succeeded by then.

Nothing is ever deleted from your library by an import. To remove a release for real, delete it in the AIOStreams dashboard.

Keeping the library honest

A release that was fine when it was grabbed can be taken down weeks later. Nothing notices on its own: the arr believes the episode is in hand, and the failure only surfaces when someone presses play.

Settings → Usenet → Library recheck re-verifies entries against your providers on a schedule keyed to how old the post is — new posts are the ones that vanish, old survivors rarely change.

A dead release is marked failed, which stops it being offered as a stream. For a release an arr grabbed, AIOStreams then goes further.

Replacing dead releases

When Settings → Sonarr / Radarr → Repair automatically (ARR_AUTO_REPAIR) is on (the default), a dead release is handed back to the linked arr that grabbed it:

1. The file record the import produced is deleted — the arr forgets a corpse.
2. The grab is marked failed, so the arr blocklists that release.
3. The arr searches again, if its own Redownload Failed setting is on. (Turn on Search after repair if it is not.)

Repair attempts per item (default 3) stops a title whose releases all come from one dead poster cycling forever: at the limit the release is blocklisted without another search and the item is unmonitored, so the arr leaves it alone until you look at it. The count resets once something imports and stays healthy.

Turn Repair automatically off to keep the detection without the action — entries are still marked failed and shown in the library, and each one has a Retry repair button.

One quiet corner of this loop: when the arr grabs a release AIOStreams already knows is dead (blocklisted), the add is refused up front — and that refusal is invisible in the arr's UI. The arr logs a warning (Couldn't add release to download queue) and drops it; there is no queue entry and no history event. The arr moves on to its next candidate, which is the point, but if a grab seems to have vanished, that log line is where it went.

Verifying contents

Settings → Usenet → Verify file contents (off by default) reads the first few kilobytes of each video file and checks it is really the container its name claims. The article audit only proves the segments exist; this catches a release that was posted or assembled wrong. It costs about one article per file.

Cleaning up stuck imports

Sometimes the arr refuses an import for its own reasons — a pack missing an episode, a title it cannot match, a file it will not treat as video. The download sits in its queue indefinitely, and nothing in AIOStreams sees it.

Settings → Sonarr / Radarr → Clean up stuck queue items (off by default) watches the queues of your configured instances and acts on the reason the arr gave:

The reasons and their default actions are listed under the toggle; you choose whether each is acted on and which action it takes. Import submits the files with the episode or movie the arr itself pre-filled, the same selection Interactive Import would show you, so it is the default for reasons where the files are fine and the arr only wants confirmation: a title it could not match, or a file name that disagrees with the release name about which episode it is. An item must stay stuck for the grace period (default 5 minutes) before anything happens, so a warning the arr clears by itself is left alone. Only downloads AIOStreams handed over are ever touched — another download client's queue items are never modified.

This reads the arrs' queues, so it needs the linked instances from the setup steps.

Using AIOStreams as an indexer

AIOStreams can also present itself as a Newznab indexer, so the arrs search through your AIOStreams configuration — your addons, filters, deduplication and sorting — instead of querying indexers directly. The feed hands back the upstream indexer's own NZB URL, so the arr still grabs from the real indexer; AIOStreams only decides which releases it sees.

In Sonarr or Radarr: Settings → Indexers → + → Newznab.

The API key is a configuration credential (the UUID from your config URL and its password), not an AIOSTREAMS_AUTH user — the feed is that configuration's results. A /api/v1/torznab endpoint exists too, for torrent results.

What it cannot do, and why RSS is the first thing to turn off:

• ID lookups only. Searches by IMDb/TVDB/TMDB id plus season and episode. Free-text search is advertised as unavailable, so an interactive search by title returns nothing.
• No RSS feed. There is nothing to list — the endpoint answers a bare query with a single placeholder item so the arr's Test passes. Untick Enable RSS on the indexer.
• One search is a full pipeline run. Every query fans out to all your configured addons, so it is slower and far heavier than a real indexer. Keep the number of indexers that hit it small.

Set ENABLE_NAB_API=false to switch both endpoints off instance-wide.

Browsing the share yourself

The content/ tree is browsable with any WebDAV client, which is handy for checking what is actually in a release.

rclone mount aiostreams: Z: --links --read-only --network-mode

Troubleshooting

Test fails in the arr. Check the URL Base is /api/v1/sabnzbd and the API Key is username:password. If the arr complains about the category, make sure the category folder is not set to something ending in * on its side.

Downloads complete but never import. Almost always the paths. Compare the arr's queue entry (its "Output Path") against what ls /mnt/aiostreams/usenet/completed/ shows inside the arr's container. If they differ, fix the mount directory setting or add a Remote Path Mapping.

A search finds nothing, or grabs never appear. Check the arr's quality profile before suspecting the feed — a profile that excludes Remux (the default "Any" profile does) rejects most of what Usenet carries, and the arr reports only 0 reports downloaded. An interactive search shows the real rejection reason per release.

The library fills with tiny files. rclone is mounted without --links, so .rclonelink files are being imported literally. Add the flag and re-import.

Imported files are broken symlinks. The mount is not visible at the same path in the media server's container, or mount propagation is missing (rshared on the mount owner, rslave on the consumers).

New downloads take a while to appear in the mount. The FUSE mount updates immediately. rclone caches directory listings for --dir-cache-time: lower it, or set Settings → Shares → rclone remote control URL if you run rclone with --rc, and AIOStreams will tell it to refresh as soon as the library changes. NFS clients wait for their own attribute cache, around 30 seconds.

Season packs or library scans hit read errors under streams.connectionLimits. Reads through the share (FUSE, NFS, WebDAV) are exempt from connection caps, so a scan opening many files at once is fine. On versions before this exemption, a per-user default like {"*": 2} also capped the share's owner — raise it or update.