⚡ nzbfast

The fast Usenet downloader - user manual

1 · Welcome

nzbfast downloads from Usenet as fast as your line, your providers, and your machine allow - and usually that means as fast as your line. It is a single self-contained program: the engine, a web dashboard, a poster-wall media browser, a built-in indexer, realtime preview, native PAR2 repair, and native RAR extraction are all inside one executable. There is nothing else to install.

What makes it fast is architecture, not tweaks:

• Pipelined NNTP: many article requests ride each connection back-to-back, keeping every connection at full speed instead of waiting out round-trips.
• A one-pass pipeline: downloading, verification, and extraction overlap. Archive volumes are extracted in the stream; on a typical store-mode post the RAR files never touch your disk, so the job needs 1× the release size, not 2×, and finishes when the download finishes.
• Multi-provider union: every configured server contributes; an article missing on one backbone is fetched from another. Slow or dead servers never stall the queue.
• A memory budget: the engine adapts to a bounded RAM allowance and degrades to disk if needed. It never swaps your machine.

Measured against the field on identical hardware, jobs and providers, nzbfast has finished a 190 GB download in around 5 minutes on a 10 GbE line, with the leading alternatives 30–220% behind on the same tests where they completed them at all. The figures are in §3.

2 · Quick start

macOS

1. Open nzbfast-<version>-macos.dmg and drag NzbFast into Applications (universal: Apple Silicon + Intel).
2. First launch: macOS warns that nzbfast isn't Apple-notarized yet. Right-click the app → Open, or open System Settings → Privacy & Security, scroll down, and click Open Anyway. This is a one-time step.
3. The app window shows the dashboard with a welcome card. Click it and add at least one Usenet server (host, port 563, username, password). You can add more later in Settings.
4. Drop an .nzb anywhere on the dashboard, or just double-click .nzb files in Finder. Downloads land in ~/Downloads/nzbfast. Quit from the menu; downloads resume where they left off.

Prefer no app? The plain zip (binary + Start nzbfast.command launcher, same engine) still works as before. The steps are below, under "From a terminal".

Windows

1. Run nzbfast-<version>-windows-x64-setup.exe. It installs for your user only (no administrator password). Because this release is not yet code-signed, SmartScreen may show "Windows protected your PC". Click More info → Run anyway.
2. nzbfast lives in the system tray: double-click the tray icon (or use Open Dashboard in its right-click menu) to open the dashboard, then add your Usenet server from the welcome card. The tray menu also has Pause/Resume, your downloads folder, and Quit.
3. Double-clicking a .nzb file queues it. Windows Defender may ask once to allow local network listening. Allow it.

Prefer a portable copy? The -windows-x64.zip still works: unzip anywhere and double-click nzbfast.exe (or Start nzbfast.bat) for the terminal wizard.

From a terminal (any platform)

nzbfast setup            # interactive server setup (writes config.local.json)
nzbfast serve --open     # start the daemon and open the dashboard

Your API key

On a genuinely new install, nzbfast makes itself an API key the first time the daemon starts, and prints it once in a banner just under the dashboard address. From then on every request needs that key, so the dashboard and the API are not open to everything that can reach the machine.

What you do with it depends on how you started nzbfast:

• The macOS app, the Windows tray, or serve --open: nothing. They pass the key to the browser window they open, the dashboard remembers it, and you are already signed in.
• A browser you opened yourself, or the dashboard on a phone or another computer: the page asks for the key once and remembers it after that.
• Sonarr, Radarr, nzb360 and friends: paste it in as their SABnzbd or NZBGet key (§11, §12).

The key is kept in a file called apikey beside your config file, so it stays the same across restarts and you can read it back whenever you need it. On macOS and Linux that file is readable only by the account that runs nzbfast. It is also in the daemon's own output, so the dashboard's Log card has it if the terminal has scrolled away.

To use a key of your own instead, type it into Settings → Security; it applies at once. That panel changes the key but never shows the current one, so read the apikey file if you need the generated value back. To run with no key at all, because something in front of nzbfast already handles sign-in, start it with NZBFAST_OPEN=1 in the environment. nzbfast then stays open and says so plainly at startup.

Which machines can reach the daemon at all is a separate choice: serve --bind. The default is 0.0.0.0, meaning every network interface, because a NAS box, a phone, and a Sonarr on another computer all have to be able to connect. --bind 127.0.0.1 narrows it to the machine nzbfast runs on, which is what you want on a single desktop where nothing else needs access.

3 · How nzbfast works

A quick vocabulary so the rest of the manual reads easily:

The pipeline runs download → decode → verify → extract concurrently. The Pipeline card on the dashboard shows all three lanes moving at once. When the last byte arrives, verification is already done and the file is already extracted; a typical job's "post-processing" time is zero. If repair is needed, only then are volumes materialised to disk, repaired in place by the native GF(2¹⁶) engine (renamed or byte-shifted obfuscated data is found and adopted by a sliding block scan), and re-extracted, all automatically.

Interrupted downloads (crash, power loss, kill -9) resume from the article journal: bytes already on disk are never fetched twice. The journal records where every article's bytes physically landed (even bytes that were direct-extracted into the final file), so a resume rebuilds from local disk and re-verifies everything it restored against the PAR2 block map before trusting it.

How that compares

Measured against SABnzbd 5.0.4 and NZBGet 26.2 on the same machine, the same providers and the same NZBs, timed to a usable file (download, verify, repair and extract all included), because that is when the job is actually done:

The gap is the post-processing the others still have to do after the last byte lands. Both competitors were tuned for the comparison, not left on defaults. SABnzbd in particular ships with request pipelining off, which costs it dearly, so it was switched on.

Two differences matter as much as the times:

• Disk space. One pass needs 1× the release size; clients that write archive volumes and then unpack them need 2×. On a test machine with 97 GB free, an 87 GB job finished here in 3 m 08 s and the other two could not run at all.
• Memory. On the 190 GB job, peak usage was 3.9 GB against SABnzbd's 9.3 GB , and nzbfast will do the same job in about 1 GB if told to (see Memory budget).

4 · The dashboard

Open http://localhost:6789 (or your machine's address from another device; the phone layout adapts automatically). Everything updates live, once a second. The cards, top to bottom:

Header bar

• Speed limit menu: fixed caps, auto · yield to LAN (an RTT-governed mode that backs off when someone else in the house needs the line), or unlimited.
• Pause for… stops everything for 15 min/30 min/1 h/3 h with automatic resume, or use the Pause button for an open-ended pause. Pause is immediate: the active transfer stops within seconds and resumes later from the journal, losing nothing. (Force-priority jobs keep downloading, SABnzbd-style.)
• An update banner appears here when a new version is available (see Updates).

Throughput

Live MB/s with a scrolling chart; the dashed watermarks mark this session's high/low, the faint line is a moving average. Below it, a histogram shows how the session's speed samples distribute: typical vs peak. Widen the window and the charts show more history (up to an hour).

Stat tiles

Downloaded this session, queue depth, completed/failed counts, session peak speed.

Resources: one machine, four ceilings

CPU, RAM (against nzbfast's memory budget), disk write rate and network on one normalized chart, with real values in the legend and a low-disk warning. No other NZB client shows you this; it exists to prove a point: nzbfast will max your line, not your machine.

Pipeline: stages overlap

Three lanes: download, verify (PAR2 blocks checked), extract. On a healthy job all three move together.

Providers

Per-server live rate, connection utilization, share of traffic, session GB, and a lifetime article-completion score (colored when a server drops below 98%). A stacked area chart shows each provider's contribution over time. Rows re-order by live performance every 10 s (configurable in Settings → Interface) so your fastest provider is always on top.

Queue

• Drag rows to reorder (within a priority band; Force/High still run first); change priority inline.
• Click a row for the detail drawer: per-file progress bars, verify block counts, which server contributed how much to this job, and an "added by" line saying where the job came from (watch folder, a connected app, the API…). A Download .nzb button saves you the job's .nzb file - nzbfast keeps its own copy, so this works for every job, even when the original file is long gone.
• Badges show special states: deferred (slow), prefetching, paused (see Performance tools).
• A burn-down chart tracks total GB remaining across the queue.

Browse index

Search everything the built-in indexer has catalogued from your watched groups (see Automation) and download with one click, no external indexer needed. The status line shows scan progress; Scan now forces a pass.

Watchlist

Add titles by name, including ones not posted yet. When a matching release appears in the index it is grabbed automatically, with quality preferences and upgrade rules (a better copy replaces a worse one).

History

Recent downloads, one row each. Failed jobs offer Retry (resumes from the journal). Encrypted archives show a 🔑 unlock control: enter the password and the job finishes in place. The verify-health strip charts bad PAR2 blocks per download: a rising tail means articles are arriving damaged. Each row's drawer says who added the job and has the same Download .nzb button as the queue - handy for downloading a release again somewhere else, or attaching the .nzb to a problem report.

The card lists ten downloads by default and the rest are one click away, on the ▤ button. Status, location and the reason a job failed live behind a click on the row itself, so the common case - what finished, how big, when - stays readable without scrolling. Drag the card's bottom edge to make the list scroll at a height you choose instead. History rows in Settings → Interface changes the ten; because it is a property of the daemon rather than of your browser, it applies to every device looking at this install. Colour History names, beside it, tints finished names green and failed ones red; turning it off leaves the names plain, and the coloured dot and the row's own details still say which is which.

Data usage

Per-provider daily bars and Today / 7-day / 30-day totals, essential for metered and block accounts. Block accounts show lifetime usage against their size.

Log, System benchmark, Connection tuning, Server diversity

An in-page log viewer, and the three self-measurement tools described in Performance tools.

5 · Adding downloads

Categories, priorities, passwords

• Categories are free-form labels; each becomes a subfolder of your download directory, and Smart Folders (see §10) can assign them by rule.
• Priorities: Force > High > Normal > Low. Force bypasses pause and quota.
• Passwords for encrypted archives are picked up automatically from <meta type="password"> inside the NZB, a Name{{password}}.nzb filename, or the p= field of an nzblnk link, and can be supplied per-job through the API or afterwards from History (🔑).

nzblnk links

Some boards, mostly German and Dutch ones, publish an nzblnk: link instead of an NZB file. The posting is obfuscated, so there is no filename anyone could link to. The link carries a header, h=, which is a search key rather than a location, plus an optional title t=, password p= and newsgroup g=. Something has to go and find the posting first.

nzbfast looks the header up in its own index to begin with, which needs no network at all, and only if that misses does it ask the search indexers you have configured (Settings → Search indexers, §9) under the same daily budgets and backoff as any other search. The title becomes the job name and the password is applied to the job automatically.

• Paste or drag works on every install, Docker and NAS boxes included: copy the link off the board and paste it anywhere on the dashboard.
• Clicking a link needs the scheme registered with your desktop. The macOS DMG app registers it, and the Windows installer offers it as a task: it asks first, and leaves the scheme alone if NZB Monkey or NZBDonkey already holds it. The plain macOS tarball, Homebrew and Linux installs have no desktop handler, so paste is the way in there.
• Resolving is rate-limited on purpose. Registering a scheme puts it one browser prompt away from any page you visit, so links are capped per minute and only the first few in a minute may reach your indexers; past that they are answered from the local index alone.

6 · The poster wall

Click 🎬 wall in the header. The wall turns your index into a media browser: every recognized film and TV release as a poster tile with rating, year, genres, cast and synopsis: your newsgroups, browsable as a catalogue.

• Tabs for Films / TV / Other, instant search, and seven sort orders: For you, Newest posts, Release date, Top rated, Title A-Z, Largest and Most posted. The ↓ button next to the sort reverses it, so every one of them also runs the other way (oldest, smallest, lowest, Z-A).
• Release date is the original release or first-air date, to the day where the metadata provider gave us one: it answers "what actually came out this week", which Newest posts cannot (that is upload date, and a re-post of a 30-year-old film lands at the top of it). Titles enriched before this existed, or whose provider had no date, fall back to their year until you refresh their metadata.
• Poster size is a slider (🔍) next to the layout buttons: drag it, or press + and -, for anything from a wall of thumbnails to a handful of large posters. Big posters and Compact each remember their own size.
• Every release of a title is listed when you open its card, with the resolution, the codec, the audio format and the dynamic range (Dolby Vision, HDR10) read out of the release name, plus size, age and whether every part is still on your provider. Set Preferred version under Settings → Organising → Indexing and the ones matching float to the top with a best match mark and the matching tags highlighted. Nothing is hidden: release names omit these tags all the time, so a preference only changes the order. It also decides which encode the watchlist upgrades to.
• Matched only is on by default, hiding unidentified junk; a "+N unmatched" chip reveals it.
• For you ranks the wall against a taste profile built on this machine from your own completed history and watchlist: favoured genres, whether you lean film or TV, and roughly which era. Titles you already have sink to the bottom rather than disappearing, and a "Because you watch …" caption says what it keyed on. With no history yet it falls back to Most posted, so it is never an empty tab. Nothing about your taste leaves the daemon.
• Not interested on any tile hides that title, and hiding a few similar ones teaches the wall: it offers a one-click filter ("Hide all Reality titles from now on?"). Everything you have hidden, and every learned filter, is listed under Hidden & filters and can be undone there.
• A small availability dot on a tile is the oracle's verdict (§13): amber "?" means uncertain on your providers, red means its parts keep coming back missing. Whole groups being actively cleared show a reaped badge.
• Click a tile for the detail sheet: synopsis, IMDb rating and votes, cast, and ▶ Play (preview it immediately, see §7) or ⬇ Download.
• ✎ Fix match: if a title matched the wrong show or film, pick the right one from candidate posters, or enter title/year/kind manually. Manual text is never overwritten by the enricher. ↻ Refresh metadata re-fetches one title; Settings → Indexing can refresh all or wipe/rebuild the whole index.
• Metadata is keyless by default: TVmaze, iTunes, IMDb datasets, Wikidata, Wikipedia and AniList need no accounts. An OMDb key (free, email-only signup; there's a signup helper in Settings → Indexing) improves film matching; a TMDB key is honoured if you already have one.

7 · Preview & verify

You don't have to wait for a download to finish to know it's the right file. Open it while it downloads, check the content, language and quality are what you expected, and cancel early if they aren't, instead of finding out after the full download.

• ▶ Play on the wall (or /m3u/<id>) hands your media player an URL; the daemon starts or reuses the download behind it.
• The /stream/<nzo_id> endpoint serves the file with full HTTP range support while it downloads. Checking any point works: spot-check minute 40 and the articles for that region are promoted to the front of the download queue. It opens there in a couple of seconds instead of minutes. The head and tail of the file are fetched first so players find their index data immediately.
• Library mode: categories listed in library_cats become instant metadata-only entries: a .strm file appears at once, availability is verified in the background, and the real download starts when you first open it.

8 · Usenet servers

Settings → Usenet servers is the full editor: add, edit, remove, reorder, and switch any server in or out of the pool. Each server has:

Leave a little headroom under your account's connection cap. Setting connections a shade below the cap costs nothing: throughput flattens out well before the last connection or two, and Connection tuning (§13) usually settles below it anyway. Those spare slots are what let a second device, another client, or a retry after a dropped socket still get in, instead of being refused while this one holds every slot.

How your provider passwords are stored

Provider passwords in config.local.json are obfuscated, not encrypted. They are stored as obf1: followed by an encoded form, so the file does not read as plain text if it appears in a screenshot, a forum post, a bug report, or on a screen someone else can see.

Be clear about what that does and does not buy you:

• It is not encryption and gives no protection from anyone who has the file. The method is in our public source and the decoder ships inside nzbfast, so anyone holding the file can recover the password in seconds. Treat the file as secret exactly as you would if the passwords were readable.
• It removes the casual leak, which is the common one. Configs get pasted into support threads and captured in screenshots far more often than they get stolen off disk.
• A password you typed in yourself as plain text still works. nzbfast reads both forms, so hand-edited configs and imports from other clients are never broken; it writes the obfuscated form the next time it saves.
• The file is also written readable only by the account running nzbfast (mode 0600 on macOS and Linux).

For comparison, NZBGet and SABnzbd both store provider passwords as plain readable text in their config files. We think obfuscation is a small improvement on that, not a security feature.

Why not the system keychain? macOS Keychain, Windows Credential Manager and the Linux secret services would give real protection, and we may revisit it. Two things stop us today. Keychain access is tied to application identity, and nzbfast is not code-signed yet, so the prompts and the behaviour after every update are poor. And a large share of installs are Docker, headless servers and NAS boxes where no keychain exists at all, which would leave two different storage paths to keep correct. A single well-understood format that behaves the same everywhere is, for now, the better trade.

Two further per-server options have no dashboard control yet: add them by hand to that server's entry in config.local.json (see §17) and restart.

• The tick beside each server is its on/off switch: ticked means the server is in the download pool, unchecked means it is disabled. A disabled server keeps its credentials and settings and can still be tested; it is simply never asked for articles. Its row dims, the heading count ("2 of 3 active") drops, and the change applies from the next download. Handy for resting a block account you are saving, or for proving one provider is behind a problem without deleting it.
• Test does a real connect + TLS + login and reports round-trip time.
• Import from SABnzbd / NZBGet… scans the usual install locations, shows what it found, and copies servers in (skipping duplicates).
• Server edits apply from the next download: no restart.

9 · Settings reference

Nearly everything is configurable from the dashboard, under ⚙ Settings; the four exceptions are listed at the end of this section. Values marked live apply immediately; restart values apply on the next launch. Every change made here is persisted to settings.json and survives restarts (UI values win over command-line flags).

Speed & scheduling live

Next download live

Connections (per server), window (pipelining depth per connection), decoders (parallel decode threads). Sampled when each job starts. Defaults are right for most lines; use the tuning tools before raising blindly.

Checking while downloading picks how much is verified as the data arrives. Full confirms every PAR2 block with MD5. Fast (the default) claims blocks by CRC32 instead, which is 2-3x quicker on a slow CPU, and still verifies every article's own checksum. Lean also skips those article checksums once PAR2 covers a file, so damage surfaces a moment later, at its block. In all three the final settle pass and any repair use full MD5, and a download with no PAR2 files keeps its article checksums.

Disk & quota live

Minimum free space (pause new jobs below it; 2 GB by default, so a disk never fills to zero, and 0 turns it off), download quota per day or month (UTC; Force jobs bypass), memory limit, the engine's RAM budget (default: ¼ of RAM, clamped; raise it on a big-RAM box for maximum speed on huge jobs, and see what low memory costs before lowering it) restart.

Move completed to: after unpack, cleanup and renaming, finished downloads move here - a NAS share, a media drive, wherever your library lives. The category layout is preserved (a job that finished under tv/ lands under tv/ at the destination), and history follows the move, so connected apps import from and delete at the new location. If the destination is unreachable when a job finishes (share offline, out of space), the files stay in the download folder and the job still completes normally. Empty = off. Per-category destinations route specific categories elsewhere (tv=/Volumes/NAS/TV, movies=/Volumes/NAS/Movies); each listed path is that category's folder, so no extra category subfolder is created inside it. Unlisted categories follow Move completed to.

Nested archive depth (default 5) is how many archive-in-archive layers are unpacked automatically: a RAR set containing a 7z containing another RAR is normal on Usenet, and nzbfast follows the chain without a second pass. At the limit the deepest archive is simply left in place, unpacked no further, and the download still completes. Raise it only for unusually deep releases.

Naming & cleanup live

Rename finished downloads (on by default) gives the folder and the main file a clean, informative name: a film becomes Example Movie (2024), TV keeps Show - S01E02. Obfuscated or unrecognized names are left exactly as posted rather than guessed at.

The whole group runs after repair and unpack and before Move completed to, and is skipped entirely for a job still waiting on a password. Both delete steps apply only to releases recognized as film or TV: a software payload or an unclassifiable (obfuscated) set is never swept.

Deleted files go to the Trash decides what "delete" means above. With it on, cleanup moves files to the system Trash or Recycle Bin, so a wrong guess about what was junk can be undone; with it off they are deleted outright. It is on by default on macOS and Windows, where the Trash is somewhere you can see and empty, and off by default on Linux, where it usually is not.

Folders & processing

Download folder restart, watch folder, post-processing script (run after every job with SABnzbd-compatible arguments and SAB_* environment; existing SAB scripts work unchanged), cleanup extensions (junk files deleted after completion), Smart Folders and TV filing (see §10).

Keep .nzb files after pickup (off by default) leaves the original .nzb in the watch folder after it is queued, instead of moving it to the Trash - for collectors, and for handing the file to someone when a download misbehaves. A kept file is remembered, across restarts too, and is not queued again; re-save it to download it again. Whichever you choose, every job's drawer has a Download .nzb button, so a copy of any job's .nzb is never more than a click away.

Indexing live

Library, Security, Interface

Library: categories treated as instant library entries + re-check interval. Security: the full API key (everything) and the NZB key (add-only, safe to give indexer sites), both rotatable live. Either box replaces the key it belongs to as soon as you leave the field, and leaving a box blank keeps the key it already has. The API key also has Show, which reveals and copies the current key so you can paste it into Sonarr, Radarr or NZB360 whenever you get round to it, and Create new, which mints a replacement - the old key stops working immediately, so anything already connected has to be given the new one. Both are gated on the API key itself: the add-only NZB key cannot read it, which is the whole point of that key being add-only. For where the key comes from on a new install, see §2. Interface: click sounds, desktop notifications on completion, provider re-sort interval.

Speed units live decides how every speed in the dashboard is shown: megabytes (MB/s, the download-manager norm, the default) or megabits (Mb/s, how ISPs quote line speeds). File sizes stay in bytes either way. This is a property of the daemon, not of your browser, so it applies to every device looking at this install.

Advanced: the tuning knobs behind the obvious ones

Six settings that have no command-line flag. Each one now has an advanced row on the settings card that owns it, and each is also settable through the API (§16), e.g. /api?mode=config&name=verify_mode&value=lean&apikey=…. Like every other setting they persist to settings.json.

10 · Automation

Watchlist

The simplest automation: add a title on the dashboard, set quality preferences, done. New releases are grabbed as they appear in your indexed groups; better-quality copies upgrade earlier grabs; a calendar view shows what's coming.

RSS feeds

Settings → RSS: any newznab/indexer RSS URL with per-feed interval, category and filter rules (title patterns, size bounds). Matching items are downloaded automatically.

Smart Folders

Rules evaluated when a job is added: match by pattern/keywords and size, assign a category (first match wins). With TV filing on, finished TV episodes are renamed and filed as Show/Season 01/Show - S01E02.mkv, ready for Plex or Jellyfin without an external tool.

Scheduler

The weekly schedule (see §9) automates pause/resume/speed by time of day.

Scripts

A post-processing script receives SABnzbd's positional arguments and SAB_* environment variables: the large ecosystem of SAB scripts runs as-is.

11 · Sonarr, Radarr & friends

nzbfast speaks the SABnzbd API natively, so every *arr works out of the box, and it can act as their indexer too.

As the download client

1. In Sonarr/Radarr: Settings → Download Clients → add SABnzbd.
2. Host: your nzbfast machine · Port: 6789 · API key: your full API key (where to find it: §2).
3. Category as desired (e.g. tv / movies). Test → green check → Save.

Queue, history, per-job status, "remove & delete", retry and category routing all behave as the *arrs expect.

As an indexer (newznab)

1. Settings → Indexers → add Newznab.
2. URL: http://<host>:6789/ · API path: /api · key: your API key.
3. nzbfast serves caps, search, tvsearch and movie queries from its own index of your watched groups, and /getnzb/<id> hands back the NZB.

12 · Phone & remote apps

nzbfast implements both major remote-control protocols, so nearly every mobile/tablet app works. Pick whichever protocol your app supports:

Apps that speak NZBGet (nzb360, LunaSea, NZB Unity…)

The full JSON-RPC surface these apps use is served: status, queue with reorder/pause/delete, history, add-NZB, speed limit, pause/resume, log.

Apps that speak SABnzbd

The dashboard on your phone

Just open http://<machine>:6789 in a mobile browser. The whole dashboard and wall have a touch layout. The Settings → Remote access panel shows the exact URLs and a QR code to scan.

Reaching nzbfast from outside your home

There is no login page, and that is deliberate. A session-cookie login is a security surface to maintain forever, and it would still be the weakest lock on anything facing the open internet. nzbfast authenticates with your API key instead, and it takes that key in a request header as well as in the URL (X-Api-Key, or Authorization: Bearer) - which is what lets something in front of it handle the sign-in properly.

The simplest answer is not to publish it at all. Install Tailscale on this machine and on your phone and both join one private network: nothing is exposed, no router or certificate work is needed, and Settings → Remote access prints a works-from-anywhere address as soon as it sees Tailscale running. Prefer this unless you specifically need a public domain.

nzbfast can also serve HTTPS itself. Point Settings → Security → HTTPS certificate / HTTPS private key at a PEM certificate and its key (or start with --tls-cert cert.pem --tls-key key.pem), restart, and the dashboard and API answer on https:// instead of plain HTTP - one listener, one scheme. Use the certificate your domain already has (for example from Let's Encrypt via certbot), or a self-signed one for the LAN, which browsers accept after a one-time warning. A bad or expired certificate refuses startup with the file named, so the mistake is visible where you made it; renew by replacing the files and restarting. Native HTTPS encrypts the traffic but does not add a sign-in, so keep the API key set.

If you need a public domain, put a reverse proxy in front, give it the certificate, and let it do the authentication. Start nzbfast with --bind 127.0.0.1 so the proxy is the only way in, and point the proxy at http://127.0.0.1:6789:

# Caddy
example.com {
    reverse_proxy 127.0.0.1:6789
}

# nginx
location / {
    proxy_pass http://127.0.0.1:6789;
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Layer on whatever your proxy offers: basic auth, a forward-auth service such as Authelia or Authentik, or client certificates. One thing catches everybody - Sonarr, Radarr and the phone apps cannot complete a browser login, so leave them a way past it. Most proxies can admit a request carrying a valid X-Api-Key header and challenge everything else.

13 · Performance tools

System benchmark

One click measures your three ceilings: network throughput (a real 8-second multi-connection probe), CPU verification rate, and disk write speed. It leads with the answer: your expected maximum download speed and which ceiling is the limit. The shortest bar is your bottleneck; the others show their headroom. Schedule it (6-hourly → weekly) and every run is logged to a history table, so you can see when your provider, ISP or hardware changed behavior. Scheduled runs only happen while the queue is idle.

Connection tuning

Measures one provider at rising connection counts and recommends the setting: more sockets help until the provider or your line saturates, and some providers punish over-asking. Test all compares every provider, then bursts them all together to check the pool saturates your line.

Server diversity

STAT-samples articles across ages on every server and clusters providers by shared gaps: providers with ~100% shared missing articles are the same backbone (redundant for recovery); independent ones genuinely extend your coverage. Ends with a plain-language recommendation.

Automatic queue intelligence

• Auto-defer: a download limping on a single slow server while other jobs wait is parked at the back (journal keeps its progress) and retried when the queue is clear.
• Idle-server prefetch: servers that can't help the active job (their copies are gone) start downloading the next queued job meanwhile. No other client does cross-job overlap.
• Cross-job soak: while a finished job's tail (verify/extract) completes on disk, the next job's download already owns the line.

The availability oracle

Takedowns are the main reason a Usenet download fails, and they are predictable: the same release goes missing on one backbone while another still has it. nzbfast keeps a small ledger of what your own providers actually answered for, and spends a tiny idle budget of STAT probes (a few hundred an hour per server, never during a download) to keep it current. It never downloads payload to find out.

What you get from it:

• An availability verdict on wall tiles and index rows (§6): amber "?" for uncertain on your providers, red for confidently gone. No mark means it looks fine.
• A reaped badge on groups where fresh posts are already being taken down, so you can tell a dying group from an unlucky release.
• Skip providers the oracle says are gone (Settings, off by default, experimental): when the check is confident one provider's backbone has lost a release, skip straight past it for that download instead of waiting for it to fail. It will never skip your last remaining provider.

The verdict is a prediction from evidence, not a guarantee. For a hard answer on one NZB, nzbfast check (§15) counts the actual articles.

Memory budget: what low memory costs

All engine caches share one budget (default ¼ of physical RAM, clamped to 256 MB–16 GB). Set it explicitly with Memory limit in Settings, or --mem-limit on the command line.

nzbfast is built to soak your network and your disk at the same time, and RAM is what lets it do both in one pass: articles are decoded, verified and written straight to their final offsets, so archive volumes need never touch the disk at all. Starve it of memory and nothing breaks: every cache has a spill path, and the engine degrades to more disk I/O rather than swapping or failing. But that spill is not free, and on big jobs you can measure it.

Measured on one machine and one line (M1 Ultra, 10 GbE), same files at each budget. Every run produced a correct, fully verified, extracted result:

Peak memory tracks the budget, not the job: that 190 GB download completes in about 1.1 GB of RAM. What you trade for it is time, and only on large jobs.

• Up to ~35 GB, low memory is free. The working set fits regardless, so a 4 GB machine finishes such a job as fast as a 64 GB one.
• Past ~87 GB you pay 20–40%, but only when your line outruns your disk. Verification blocks and archive volumes that would have stayed in RAM get written out and read back instead, and that only costs time if the network can deliver faster than the disk can absorb the extra traffic. The 20–40% above was measured on 10 GbE; the same 87 GB job at the same budgets on a ~2.4 Gbps line showed no penalty at all (−1 to +7%, within run-to-run noise). The penalty is a function of how far the line outruns the disk, not of the job size. On a typical home connection a small budget is close to free even on very large jobs.
• The penalty plateaus. Once a job is large enough to spill, every constrained budget spills about the same amount: the 2 GB, 1 GB and 256 MB runs read back essentially the same number of blocks from disk, and finish within noise of each other. So a little more RAM below the threshold that avoids spilling entirely doesn't buy back the cost: give it enough to keep the job in memory, or the exact figure barely matters.

On a small NAS, also drop Connections (2–4) along with the budget. At a 256 MB budget and 2 connections, peak memory stays near 190 MB, comfortably inside what a 2 GB NAS has spare. Be aware that at that point the connection count, not the memory, is what limits you: the same 35 GB job took 286 s instead of 65 s. That is the honest shape of the trade: it will always finish, and finish correctly; it just won't soak the line.

Benchmarks are re-run for each release; method and per-machine figures are published alongside the results.

14 · Updates

• Updates are notify-only: nzbfast never downloads or replaces its own binary, and there is no code in it that can. When a new release exists, the header shows ⬆ v X available - download; the chip links to the official download page (the link is fixed in the app, it never comes from the update manifest). Install the new version the same way you installed the current one.
• nzbfast checks for new releases twice a day. Turn Check for updates (Settings) off and it never contacts the update manifest at all; an empty update check URL does the same.

Updating without losing your settings

One rule covers every install: an update replaces the program, never your settings. Everything you have configured - servers, paths, the API key, the queue - lives in a handful of files in one folder (§17), and no installer, image pull or package upgrade touches that folder. When settings do look gone after an update, it is almost always because the new install is reading a different, empty folder, not because anything was deleted; the old files are still where they always were. §18 has the recovery steps.

15 · Command line

Everything the daemon does is also scriptable. The everyday commands:

Also available: inspect, probe, bench, bench-cpu, soak, fetch, spots/spot-search/spot-get (Spotnet), predb-seed (fills the pre database from before the feed was switched on), make-release-nzb/make-test-nzb (test fixtures), and post (uploads files as yEnc articles and writes the matching NZB; an operations tool, it requires an explicit --post-server and never picks a server for you). Every command takes --config and --help.

16 · API overview

Base endpoint: http://host:6789/api?mode=…&apikey=…&output=json. It is SABnzbd-compatible, so existing SAB integrations work unchanged. Two keys: the API key (full control) and the NZB key (add-only: addfile/addurl). addnzblnk is deliberately not in the add-only set: resolving one can spend metered indexer quota, which an add-only credential has no business doing.

17 · Files & locations

Where the settings folder is depends on how nzbfast was installed. This one folder holds everything worth backing up:

And what is inside it:

18 · Troubleshooting

This manual ships with every release. Settings, endpoints and defaults referenced here match the version it shipped with.