Shelfarr: open it, first login, settings, fixes
· Updated 18 September 2026 · SparkBox team
A request-and-automation app for ebooks and audiobooks. Shelfarr searches the indexers and sources you configure, sends a selected release to your download client, then delivers the finished book to your ebook or Audiobookshelf library. This is the short card for it — the two minutes after you press Enable, and the page to come back to when something is off.
Open it
Dashboard → Apps → Shelfarr → Open. Shelfarr is kept off your network on purpose, so typing your box's IP and a port into a browser will not reach it.
On its card, click choose access and pick how you want to reach it: a private Tailscale link, or a domain you put behind the proxy.
Create the admin account first, then connect one indexer and one download client before inviting requesters.
First login
No default account. The first person to register becomes Shelfarr's administrator, so create the admin account as soon as you enable it and keep the page on your LAN or private VPN.
Worth knowing
- Connect Prowlarr at http://sb-gluetun:9696 and qBittorrent at http://sb-gluetun:8080 when you use SparkBox's Media stack.
- For qBittorrent path mapping, set the remote path to /data/downloads and the local path to /downloads.
- Connect Audiobookshelf at http://sb-audiobookshelf:80. Finished ebooks go to your SparkBox books folder and audiobooks go to your audiobook folder.
- Shelfarr's optional direct-download and store integrations start disabled. SparkBox does not configure or endorse third-party content sources; only download content you are legally allowed to access.
- The optional Audible/Libation companion is not included in this first SparkBox module.
Connect it to the SparkBox media apps
Use Docker service names, not your NAS IP, when Shelfarr talks to apps on the same SparkBox:
- Prowlarr URL:
http://sb-gluetun:9696 - qBittorrent URL:
http://sb-gluetun:8080 - Audiobookshelf URL:
http://sb-audiobookshelf:80
Copy each app's API key or password from that app. SparkBox never puts those credentials into Shelfarr automatically.
Use the matching download paths
SparkBox's qBittorrent sees completed downloads under /data/downloads; Shelfarr sees that same host folder at /downloads. In Shelfarr, set download_remote_path to /data/downloads and download_local_path to /downloads. This mapping is what lets Shelfarr find and import a completed book.
The output paths are already mounted: /audiobooks for Audiobookshelf and /ebooks for the SparkBox books folder.
Choose sources deliberately
Shelfarr includes optional integrations for indexers, direct-download sites, public-domain catalogs, and a beta store lookup. They are all unconfigured or disabled on a fresh SparkBox install. SparkBox ships the app, not books, accounts, indexers, trackers, or source access. Check the law and the provider's terms where you live before enabling anything; keep questionable integrations off.
When it breaks
If it will not open, check the app card first — a red dot means it is restarting or unhealthy, and this walkthrough reads the reason from its log. Tom AI on the dashboard can do the same for you.
Where your data lives
/opt/sparkbox/modules/shelfarr/config/Included in the dashboard's Backup by default. Restoring that backup on a fresh install brings Shelfarr back exactly as it was.
Questions, or did this not match your box?
Every guide here came from a real problem someone hit. If yours behaves differently, say so — that is how these get corrected, and how the fix gets prioritised.
We answer there rather than in a comment box, because that is where the people who have already solved it are.