Listenarr

Automated audiobook and eBook collection management

Overview

Listenarr is an audiobook and eBook downloader in the *arr style — think Sonarr or Radarr, but for books. It monitors your favorite authors and titles, enriches metadata from Audible, Amazon, and OpenLibrary (covers, narrators, series data — all built in, no separate indexer app needed), and hands grabs to the download clients you already run: qBittorrent, Transmission, SABnzbd, or NZBGet.

QuickBox Pro installs Listenarr per user as a self-contained build: the release ships everything in a single package, so there is no host runtime to install or maintain. The application code lives under /opt/username/Listenarr/, all of your data lives in one state tree under /home/username/.config/Listenarr/, and a per-user systemd service serves the UI at https://your-server/username/listenarr/ through the nginx reverse proxy — bound to localhost only, with nginx as the sole public entry point.

Key features

When to use it

Installation

Install from the QuickBox CLI

qb install listenarr -u username

The install downloads the newest upstream release, extracts it into the per-user install tree, patches the bundled web client for your personal URL path, and starts the service. There is no compile step and no runtime provisioning — installs complete in well under a minute on a typical connection.

CLI commands

Install flags

Install from the Dashboard

You can also install Listenarr from the QuickBox Pro dashboard. The dashboard installs for the currently signed-in user — there is no user picker on the install dialog. To install for a different user, use the CLI with an explicit -u <other_user>.

To install from the dashboard:

1. Open App Dashboard → Package Management (/dashboard?mode=packages)
2. Find Listenarr under the Media Management category
3. Submit — a live install log streams in the response modal

The dashboard runs the same install pipeline as the CLI.

Access and authentication

URL

Listenarr is published under the per-user subpath of your QuickBox server:

https://your-server/username/listenarr/

The bundled web client is patched for this exact path at install time, so the subpath is served natively — including the WebSocket connections that power live download progress and log streaming. You can also click Open on the Listenarr row in the dashboard’s App Dashboard to launch the UI directly.

Enable authentication first

To lock your instance down:

1. Open https://your-server/username/listenarr/
2. Go to Listenarr’s Settings and enable authentication
3. Set a username and a strong password, then save — the UI switches to a login page from that point on

QuickBox does not generate, write, or store any Listenarr credentials — there is no default password, no credentials file, and nothing to reveal in the dashboard. The account exists only after you create it inside the app.

API key

Listenarr auto-generates its API key on first start and stores it in its own database. View it inside the app’s Settings when a download client, script, or companion tool asks for it. There is no API key file on disk, and the dashboard does not display it.

Configuration and files

Listenarr keeps the application install and your data in two separate trees. Everything that matters to you — the database, settings, and logs — lives under /home/username/.config/Listenarr/. The install tree under /opt/username/Listenarr/ carries zero state and is fully replaced on every update.

Nearly all of Listenarr’s settings live in its SQLite database and are managed through the web UI — appsettings.json exists, but you will rarely need to touch it. The listen port and the state-tree location are managed by QuickBox through the systemd unit and kept in sync with nginx and the QuickBox database automatically.

Service management

Listenarr runs as a single per-user systemd unit:

# Check status
sudo systemctl status listenarr@username
 
# Restart / stop / start
sudo systemctl restart listenarr@username
sudo systemctl stop listenarr@username
sudo systemctl start listenarr@username
 
# Follow the service log
sudo journalctl -u listenarr@username -f

The service starts automatically at boot. Listenarr’s database migrates itself during startup after an update — no manual migration step is ever needed; the web UI simply answers once the migration completes (typically a few seconds). The systemd journal carries the full service output and is the first place to look; Listenarr also writes date-rolled log files under /home/username/.config/Listenarr/config/logs/.

Common tasks

Enable authentication

Do this first — see Enable authentication first above. Open the app, go to Settings, enable authentication, and set a username and strong password.

Add a download client

1. In the Listenarr UI, open the download client settings
2. Add your client — qBittorrent, Transmission, SABnzbd, or NZBGet — with its host, port, and credentials
3. On a QuickBox server your clients run on the same machine, so localhost plus the client’s assigned port is the usual shape
4. Test the connection and save — Listenarr hands every grab to the client from then on

Update Listenarr

qb update listenarr -u username

The update stops the service, replaces the install tree with the newest release on your recorded channel, re-patches the fresh web client for your URL path, and starts the service again. Your database, settings, and logs are untouched — all state lives outside the install tree. Add --beta to pull the newest canary build for that update run.

Check the logs

# Service output (the canonical log stream)
sudo journalctl -u listenarr@username -f
 
# In-app date-rolled log files
ls /home/username/.config/Listenarr/config/logs/

Back up your data

Everything worth keeping lives in one tree. Back it up while the service is stopped for a clean snapshot:

sudo systemctl stop listenarr@username
tar -czf ~/listenarr-backup.tar.gz -C /home/username/.config Listenarr
sudo systemctl start listenarr@username

QuickBox also snapshots listenarr.db into /home/username/.QuickBox/software/listenarr/ during installs.

Remove Listenarr

qb remove listenarr -u username

Troubleshooting

Best practices

FAQ

Resources