StreamNZB is the one place you configure Usenet. Providers, indexers, filter and ranking rules, search requests and metadata all live in a single binary — and everything else consumes that configuration. Set a provider up once and every app you point at StreamNZB gets it, with your credentials and API keys staying on the server.
The playback engine underneath streams releases on-the-fly from your providers, recovers obfuscated releases from their own bytes, and rebuilds a missing first RAR volume from PAR2 recovery data rather than giving up on the release.
It also watches what it is configured with: when a provider rejects your password or an indexer revokes your API key, StreamNZB says so on the dashboard, routes around it, and re-checks until it works again.
| From | What it gets | Docs |
|---|---|---|
| Stremio | A complete addon: catalogs, search, title pages, air dates and streams. No Cinemeta, no companion addons | Metadata & catalogs |
| Prowlarr, Sonarr, Radarr | Every indexer you configured, as one Newznab API behind one key | Newznab endpoint |
| SABnzbd, NZBGet | Your whole provider pool, as one NNTP server | NNTP proxy |
| AIOStreams | StreamNZB as a preset, alongside what it already runs | Using with AIOStreams |
One config, one IP, no extra containers — just your Usenet provider(s) and indexer(s). See Integrations for the whole picture in one page.
- Configure once, use everywhere — Define global providers, indexers, search queries and filter profiles once, then create one or more streams that decide which of those resources belong to each manifest. The same configuration backs the Newznab endpoint and the NNTP proxy, so adding a provider or swapping an indexer is one edit, not one per app.
- Knows when a provider or indexer stops working — Rejected credentials, a lapsed subscription, a spent daily quota or a connection limit are detected from what the server actually answered, shown on the dashboard and on the affected card, and routed around until they clear. See Indexer & provider health.
- The only addon you need — StreamNZB serves catalogs and full metadata alongside streams: trending/popular/top-rated rows, search, series pages with episode lists and exact air dates, plus per-stream Continue Watching and Because You Watched rows built from your own playback history. Works out of the box in any Stremio-compatible client, including ones without Cinemeta.
- Standalone Stremio Addon — Install StreamNZB directly into your Stremio client with built-in release parsing and ranking powered by jhin, customizable filter profiles, or optionally plug it into AIOStreams.
- Newznab endpoint — Every configured indexer re-served as a single Newznab API (off by default), so Prowlarr, Sonarr, Radarr or any Newznab client searches the whole set through one URL and one key. Your indexers' own API keys are never handed to the client.
- NNTP proxy — Standard NNTP (default port 1119, off by default) for SABnzbd or NZBGet. Shares the same provider pool as the addon.
- AvailNZB — Community availability database, opt-in. Bad releases are skipped; success/failure is reported on play so the shared DB stays current. Off by default, and nothing is sent until you enable it.
- Search history & diagnostics — The History page shows every search with its play attempts nested under it: per-indexer API timings, what validation/dedup/filtering dropped and why, including searches that returned nothing. An optional Search debug stream toggle (under Advanced) prepends the same summary as a result row in Stremio — selecting it just plays the top real result.
- SQLite or Postgres — A local file by default, or point it at an existing Postgres server. Switching migrates your data either way, without a restart.
- Single binary — Docker image or native Windows/Linux/macOS. No other containers required.
Enabled is not the same as working. A password changed at your provider, an API key revoked by an indexer, a subscription that lapsed on a card that expired — none of those flip a switch in your configuration. Without something watching for them, they surface as searches quietly returning less and playback quietly failing over, days after the fact.
StreamNZB tracks whether each provider and indexer is actually usable as a fact separate from whether you enabled it. Your switch is never touched, so it always means what you set it to.
| State | What it means | What happens |
|---|---|---|
| OK | Nothing to report. | Normal use. Nothing is shown — an unhealthy list that is empty when all is well is one you can trust when it isn't. |
| Degraded | Working, but limited: daily quota spent, or the indexer asked us to back off. | Keeps being used where it can be. Ends on its own. |
| Blocked | The server rejected the account itself. | Blocked indexers sit out searches; blocked providers drop behind healthy ones instead of being raced first. |
Only a definitive rejection blocks anything. A newznab 1xx credential code, an HTTP 401, an NNTP 481 — those are verdicts on the account. Timeouts, 5xx responses and rate limits are not, and never retire a working key over one bad afternoon at an indexer.
It is shown where you would look for it: a Usenet health panel on the dashboard naming what is wrong, since when, and what to do about it; a badge on the indexer or provider card in Settings; and a live push to the open UI, so a subscription that lapses mid-session appears while you are watching rather than on your next refresh.
And it recovers by itself. Blocked components are re-checked automatically — 15 minutes after the failure, backing off to hourly while the answer stays no — so a renewed subscription heals with nobody clicking anything. Fixing the credentials in Settings clears the verdict immediately, and Check again re-checks on the spot, including for a provider whose password was already wrong when StreamNZB started.
Full behavior, reason codes and API in Indexer & provider health.
Playing from an archive without downloading it first means seeking to an arbitrary byte inside it. That is possible when the inner file is stored (no compression) and impossible when it is compressed, because reaching byte n of a compressed stream means decoding everything before it. This is a property of the formats, not of StreamNZB — Stremio's own addon SDK documents its native 7zip support as "supports seeking only when compression is not used", and every streaming implementation lands in the same place.
Plays:
- RAR in STORE mode, RAR4 and RAR5, including multi-volume sets — which is how scene and P2P releases are packed.
- 7z with copy/store content.
- Encrypted RAR and 7z, where the NZB carries the password — AES sets are decrypted as they stream.
- Obfuscated releases, where the filenames were stripped before upload. Names are recovered from the release's own bytes — see Obfuscated releases.
- Damaged releases, up to a point. Isolated missing articles are zero-filled and playback continues; a missing first RAR volume is repaired from PAR2 recovery data rather than failing the release. See Troubleshooting.
Does not play:
- Compressed RAR or 7z. Not streamable by anyone, per the above. Such a release has to be downloaded and unpacked — point SABnzbd or NZBGet at the NNTP proxy if you want that from the same provider pool.
Stremio v5 can stream NZBs natively on desktop, with Android TV in beta. Two reasons to keep playback on the server anyway:
- Every other client. Web, iOS, Android mobile and TV platforms have no native path; StreamNZB serves all of them the same way.
- Your provider credentials stay put. The native path passes NNTP server strings — username and password included — to the client in the stream object. Through StreamNZB they never leave the server, and playback comes from one IP.
Docker (recommended):
services:
streamnzb:
image: ghcr.io/gaisberg/streamnzb:latest
container_name: streamnzb
restart: unless-stopped
ports:
- "7000:7000"
- "119:119"
volumes:
- /path/to/config:/app/dataOr run the binary from the releases page (Windows, Linux, macOS). See Configuration for startup flags and config via environment variables.
- Open
http://localhost:7000. Default login isadmin/admin; you'll be asked to change the password. - Go to General (under Settings) and set your addon Base URL and Port.
- If using Tailscale, use the IP address of the machine running StreamNZB. Example:
http://100.64.0.1:7000 - If using a domain name, make sure it is reachable from your client. Example:
http://streamnzb.example.com:7000orhttps://streamnzb.example.com - Changing the port takes effect immediately, without a restart — but it closes the connection this page is served over, so reopen StreamNZB on the new port afterwards.
- If using Tailscale, use the IP address of the machine running StreamNZB. Example:
- Go to Providers and add at least one Usenet provider (host, port, username, password, connections).
- Go to Indexers and add at least one Newznab-compatible indexer (URL + API key).
- Go to Filters to configure release filtering profiles and ranking rules.
- Go to Search and configure your movie and/or TV search queries.
- Optionally go to Metadata to curate the catalogs your clients see (trending rows are on by default) — see Metadata & Catalogs.
- Go to Streams and click Add Stream to create a stream manifest.
- Select which providers, indexers, search queries, and filter profiles belong to this stream.
- Configure stream options such as indexer mode, search query mode, results mode, failover, and AvailNZB behavior.
- Click Install on your stream to add the manifest directly to your Stremio client (or copy the manifest URL for optional use in AIOStreams).
Full reference documentation lives in the docs folder:
- Configuration — startup flags, data directory, and the full environment variable reference
- Database backends — SQLite (default), Postgres, and switching between them
- Remote access — VPN and reverse proxy setups for streaming away from home
- Providers — priority, failover, and holding a metered account back as a backup
- Provider speed test — measuring provider throughput and finding the right connection count
- Indexer & provider health — how a rejected password, spent quota or lapsed subscription is detected, shown and recovered
- Easynews advanced search — server-side filtering options for Easynews indexers
- Metadata & catalogs — StreamNZB as a full Stremio metadata provider
- Stream model — global configuration vs. per-stream behavior
- Filters & ranking — filter profiles: what gets rejected, how the rest is scored and ordered
- Rules — named conditions over everything known about a release
- Custom result formats — per-stream result templates, helper reference, and the AIOStreams formatter import
- Search requests — how indexer queries are built, executed and validated
- Obfuscated releases — how releases with random-hash filenames are identified and played
- Integrations — one configuration serving Stremio, Prowlarr/*arr and your download client
- NNTP proxy — using StreamNZB as a local news server for SABnzbd/NZBGet
- Newznab endpoint — serving your configured indexers to any Newznab-compatible application
- AvailNZB — community availability database integration
- Using with AIOStreams — what StreamNZB adds alongside it, and how to add it as a preset
- Troubleshooting — reporting problems, Cloudflare Tunnel buffering, admin password recovery
- Backup & updates — what to back up and how to update safely
If you're stuck, please either open a GitHub issue or report it in the Discord #help channel (they sync via GitThread). See the troubleshooting guide for what to include and common issues.
If StreamNZB is useful to you, you can support development here:
- dreulavelle for jhin (the release parsing & ranking engine) and contributions.
- javi11 for Go-based RAR and 7z streaming (altmount).