
AudioBookShelf
Self-hosted audiobook and podcast server
Overview
AudioBookShelf is a self-hosted audiobook and podcast server. It organizes your audiobooks and podcasts into libraries, keeps your listening position in sync across the web client and the official iOS and Android apps, subscribes to podcast RSS feeds with automatic episode downloads, and matches rich metadata (covers, narrators, series, chapters) from Audible, iTunes, and Google Books. AudioBookShelf ships its own complete multi-user authentication — you create the admin account in your browser on first visit, and manage additional users with per-library permissions inside the app.
QuickBox Pro installs AudioBookShelf per user, built from source: the installer clones the latest upstream release tag, provisions an isolated Node.js runtime maintained to the QuickBox security minimum for your user, compiles the native SQLite bindings, and generates the web client with your personal URL path baked in. The result is a single systemd service served at https:// through a clean nginx reverse proxy — no rewrites, no path tricks. Docker images and the upstream .deb package are upstream alternatives and are not used by the QuickBox package.
Because the install is a real source build, the first install (and every update) takes noticeably longer than a binary application — expect several minutes while dependencies compile and the web client is generated.
Key features
Audiobook & Podcast Library
Organize audiobooks and podcasts with chapters, series, collections, and per-book progress tracking
Progress Sync
Listening position stays in sync across the web client and the official iOS and Android apps in real time
Podcast Auto-Download
Subscribe to RSS feeds with scheduled episode downloads, retention rules, and episode search
Metadata Matching
Covers, descriptions, narrators, series, and chapters from Audible, iTunes, and Google Books
Built-In Multi-User Auth
Per-user accounts with granular library permissions; the admin account is created in-browser on first visit
Mobile Apps
Official iOS and Android apps with offline listening and background playback
Per-User Service
Security-maintained, isolated Node.js runtime and systemd unit audiobookshelf@username with auto-allocated port and loopback-only binding
Reverse-Proxy Ready
Native nginx subpath at / with WebSocket support and optional custom-domain SSL
When to use it
Good fit
- You want a self-hosted home for your audiobook collection with chapter support and progress tracking
- You want podcast subscriptions that download new episodes automatically
- Multiple people share your audiobook library and need their own accounts and listening positions
- You listen on the go and want official mobile apps with offline playback
What you get
- Install via
qb install audiobookshelf -u username— built from source with an isolated Node.js runtime maintained to the QuickBox security minimum - Served at
https://by default, with optional custom subdomain and SSLyour- server/ username/ audiobookshelf/ - Single per-user systemd service
audiobookshelf@usernamewith auto-start on boot - For a full music server, look at Airsonic or Subsonic instead; for comics and manga, look at Kavita or Komga
Installation
Install from the Dashboard
Open App Dashboard → Package Management (/), find AudioBookShelf under the Media Servers category, and click Install. The dashboard streams the install log live and AudioBookShelf appears in your Application Control panel when it finishes. Reinstall and Remove are in the same Package Management panel. To update, use the amber Update badge on the AudioBookShelf row in the App Dashboard.
In the install dialog you can switch the Custom Domain toggle to Custom and enter a domain — the install issues an SSL certificate and publishes AudioBookShelf on that subdomain (see Custom subdomain with SSL). Choose HTTP-01 (the default) or DNS-01 as the challenge method; DNS-01 also asks for the DNS provider.
The dashboard installs AudioBookShelf for the currently signed-in user; to install it for a different user, an admin uses the CLI with an explicit -u <other_user>. For the full package flow see App Management.
Install and manage from the CLI
The CLI runs the same install pipeline and is suited to automation and scripting. The -d domain (and optional --dns/--dns-) map to the Dashboard custom-domain fields above:
qb install audiobookshelf -u username
qb install audiobookshelf -u username -d audiobookshelf.example.com
qb update audiobookshelf -u username
qb reinstall audiobookshelf -u username
qb remove audiobookshelf -u username
qb help audiobookshelfReinstall removes application state, including library accounts and progress. Back up and restore before reinstall or remove.
AudioBookShelf tracks stable tagged releases only — there is no --beta flag. Full flag reference: CLI Reference.
AudioBookShelf publishes no prebuilt Linux binaries, so QuickBox builds it from source. The first install and every update spend several minutes on dependency installation and the web client build — this is normal. You can follow the build in /.
The upstream default port is 3333, but QuickBox assigns each user their own free port at install time and binds it to 127. only — nginx is the sole public entry point. The assigned port is recorded in the QuickBox database and shown on the AudioBookShelf row in the dashboard’s App Dashboard. You never need to touch it.
Access and authentication
URL
AudioBookShelf is published under the per-user subpath of your QuickBox server by default:
https://The web client is generated with this exact path baked in, so the subpath is served natively — including the socket.io WebSocket connection that powers real-time progress updates. You can also click Open on the AudioBookShelf row in the dashboard’s App Dashboard to launch the UI directly. When AudioBookShelf is published on a custom subdomain (see Custom subdomain with SSL below), the Open link points at https:// instead.
First-run setup
AudioBookShelf manages its own accounts. On your first visit, the app shows an initialization screen where you create the admin (root) account in the browser — pick a username and a strong password. QuickBox does not generate, write, or store any AudioBookShelf credentials; there is no default password and no credentials file to retrieve.
- Open
https://your- server/ username/ audiobookshelf/ - On the initialization screen, create the root user — choose a username and a strong password
- Sign in with the account you just created
- Create your first library: pick Books or Podcasts, then add one or more folders that hold your media
- AudioBookShelf scans the folders and matches metadata automatically
Additional accounts, per-library permissions, and all other user management live inside the app under Settings → Users. These AudioBookShelf accounts are separate from QuickBox accounts — every QuickBox user who installs AudioBookShelf gets their own private instance with its own users.
Unlike some QuickBox applications, there is no auto-generated admin password for AudioBookShelf and nothing to reveal in the dashboard. The root account exists only after you create it in the browser, and AudioBookShelf stores it in its own database.
Custom subdomain with SSL
By default AudioBookShelf serves under the per-user subpath of your main server address. You can also publish it on a dedicated subdomain (for example audiobookshelf.) with a Let’s Encrypt certificate. There are three ways to set this up: a single-call install (Path A), a post-install retrofit from the CLI (Path B), and the dashboard SSL Control page (Path C).
AudioBookShelf bakes its serving path into the web client at build time. Whenever the install flips between the per-user subpath and a custom subdomain — in either direction — QuickBox automatically rebuilds the client for the new base. The service stops during the rebuild and starts again when it finishes; expect a few minutes of downtime for the flip. Your library, users, and progress are not affected.
Path A — Subdomain at install time
The fastest path is to pass -d <domain> to the install. The certificate is issued, the subdomain vhost is written, and the web client is built for the subdomain on the first try — you never see the subpath URL.
Point a DNS record (A or CNAME) for your chosen subdomain at the server, then run:
qb install audiobookshelf -u username -d audiobookshelf.example.comThe install chain-calls Let’s Encrypt under the hood and auto-detects any saved DNS provider credentials, switching to the DNS-01 challenge automatically when it finds them. To force the DNS-01 challenge explicitly:
qb install audiobookshelf -u username -d audiobookshelf.example.com --dns --dns-provider cloudflarePath B — Retrofit a subdomain to an existing install
If AudioBookShelf is already running on the per-user subpath and you want to move it to a dedicated subdomain, issue the certificate with the AudioBookShelf-specific lecert flag:
qb install lecert --audiobookshelf -d audiobookshelf.example.com -u usernameThis uses the same shape as every other lecert-managed application (--emby, --jellyfin, --plex, --komga, etc.). QuickBox:
- Requests a Let’s Encrypt certificate for the supplied domain (HTTP-01 challenge by default)
- Writes the subdomain vhost into
/with your assigned port filled inetc/ nginx/ sites- enabled/ username. audiobookshelf. conf - Stops the service, rebuilds the web client for the subdomain root, and starts it again
- Reloads nginx and registers the certificate for automatic renewal
Wildcard or DNS challenge: add --dns --dns- (or another supported provider). See the Let’s Encrypt application reference for the full list of supported DNS providers.
Testing without rate-limit exposure: add --staging to issue against the Let’s Encrypt staging CA, or --dry- to validate the ACME challenge without writing any certificate or nginx changes. Combine the two to fully exercise the flow with zero side effects.
Removing the subdomain: qb remove lecert --audiobookshelf -d <domain> -u username deletes the subdomain vhost. If AudioBookShelf is still installed, QuickBox rebuilds the web client for the per-user subpath and restores the subpath nginx config, so subpath access continues to work.
Path C — Dashboard SSL Control
The dashboard’s SSL Control page at System → SSL Control (/) exposes the same flow. The form fields, in order, are:
- Target — pick AudioBookShelf from the dropdown
- Domain — your chosen subdomain (for example
audiobookshelf.)example. com - Challenge Method — HTTP-01 (the default) or DNS-01
- DNS Provider — only shown when DNS-01 is selected
- DNS credentials — only shown when DNS-01 is selected and no credentials are saved for that provider yet
- Username — the QuickBox user that owns the install
The SSL Control page runs the same qb install lecert --audiobookshelf pipeline under the hood.
For end-to-end SSL setup, supported DNS providers, wildcard certificates, and renewal behavior, see the SSL Certificates dashboard page and the Let’s Encrypt application reference.
Configuration and files
AudioBookShelf keeps the application install and your library state in two separate trees. Everything that matters to you — the database, covers, cached metadata, and logs — lives under /. The install tree under / is disposable and is rebuilt on every update.
AudioBookShelf has no text settings file — all in-app settings live in the SQLite database and are managed through the web UI. The only file QuickBox manages is env., which carries the runtime environment the systemd unit loads (port, bind address, data paths, and serving base). It is kept in sync automatically by installs, updates, and SSL flips.
The managed nginx config allows uploads up to 10 GB per file for audiobook and podcast uploads through the web UI, and holds WebSocket connections open for real-time progress sync. You do not need to tune nginx yourself.
Service management
AudioBookShelf runs as a single per-user systemd unit:
# Check status
sudo systemctl status audiobookshelf@username
# Restart / stop / start
sudo systemctl restart audiobookshelf@username
sudo systemctl stop audiobookshelf@username
sudo systemctl start audiobookshelf@username
# Follow the service log
sudo journalctl -u audiobookshelf@username -fThe service starts automatically at boot. The application’s SQLite database migrates itself on start after an update — no manual migration step is ever needed. In-app daily logs are also written to /, but the systemd journal carries the full output and is the first place to look.
Common tasks
Add an audiobook library
- Sign in and click the library switcher in the top bar, then Add Library (or go to Settings → Libraries)
- Choose Books as the media type and add the folder(s) that hold your audiobooks
- Save — AudioBookShelf scans the folders and matches covers, series, narrators, and chapters automatically
Subscribe to a podcast with auto-download
- Create a library with the Podcasts media type pointed at a folder for episode storage
- In the podcast library, click Add → Podcast and search by name or paste an RSS feed URL
- On the podcast’s page, enable Auto Download Episodes and set the check interval and retention to taste
Update AudioBookShelf
qb update audiobookshelf -u usernameThe update backs up your database, fetches the newest stable release tag, rebuilds the server dependencies and the web client with the same serving base the install is using, and restarts the service. Your library, users, and progress are untouched — all state lives outside the install tree. Like the install, the update is a source build and takes a few minutes.
Check the logs
# Service output (the canonical log stream)
sudo journalctl -u audiobookshelf@username -f
# In-app daily logs
ls /home/username/.config/audiobookshelf/config/logs/
# QuickBox install/update build log
tail -f /opt/quickbox/logs/audiobookshelf.logBack up and restore
QuickBox backs the AudioBookShelf database up for you from the dashboard or the CLI, with no need to stop the service and archive the folder by hand. Every backup is saved to /.
| Backup | What it saves |
|---|---|
| Config Only | absdatabase., the database that holds your user accounts, listening progress and library settings, as absdatabase. plus a copy named absdatabase. that is always the latest |
| Full Backup | Two archives: audiobookshelf-<version>-config_<date>.tar. holds the data folder / with a consistent copy of absdatabase. (logs are left out), and audiobookshelf-<version>-application_<date>.tar. holds the install tree |
| Nginx | AudioBookShelf’s nginx config, username. |
Config Only does not include the covers and cached metadata under /; Full Backup does. Your audiobook and podcast media files are never part of a backup.
From the dashboard: open Content → Asset Management Center (AMC in the sidebar), choose the Application Backups tab, expand the AudioBookShelf row and click Back up now, then pick Full Backup, Config Only or Nginx. The same row lists every saved file with download and delete buttons. To restore, open the App Dashboard, stay on Application Control, expand the AudioBookShelf row and click Restore in the Operations section, then pick the backup; for a full backup the button reads Rollback and puts back both archives. Restore appears only when your account is allowed to restore backups. See App Management → Application Backups for who can see the tab.
From the CLI:
# Config Only: absdatabase.sqlite
qb manage software -o backup -u username -s audiobookshelf
# Full Backup: the data folder and the install tree
qb manage software -o backup -o app -u username -s audiobookshelf
# Put back the most recent database backup
qb manage software -o restore -u username -s audiobookshelf
# Roll back to a Full Backup: pick the version from a menu, then confirm
qb manage software -o rollback -o app -u username -s audiobookshelfEvery option is described in the qb manage reference.
The backup folder belongs to the app: qb remove audiobookshelf and qb reinstall audiobookshelf both delete / with every backup in it. Before either one, download the Full Backup from the Application Backups tab, or copy the folder somewhere QuickBox does not manage:
cp -a /home/username/.QuickBox/software/audiobookshelf/backup /home/username/audiobookshelf-backup-savedRestore your accounts and progress after a remove
Put the saved database back into the fresh install with the service stopped. Run the file commands as your own account:
qb install audiobookshelf -u username
sudo systemctl stop audiobookshelf@username
rm -f /home/username/.config/audiobookshelf/config/absdatabase.sqlite-wal /home/username/.config/audiobookshelf/config/absdatabase.sqlite-shm
cp /home/username/audiobookshelf-backup-saved/absdatabase.sqlite /home/username/.config/audiobookshelf/config/absdatabase.sqlite
sudo systemctl start audiobookshelf@usernameRemoving the -wal/-shm files first stops the new install’s journal from being applied to the restored database. Your accounts and listening progress come back as they were in the backup; covers and cached metadata are not in a Config Only backup.
Remove AudioBookShelf
qb remove audiobookshelf -u usernameBoth qb remove audiobookshelf and qb reinstall audiobookshelf delete the full per-user state tree at / — the database, every user account, listening progress, covers, cached metadata, and logs — along with the install tree and the per-user Node runtime. Download a backup and copy it out first (see Back up and restore) if there is any chance you will want your accounts and progress back. The backup folder at / is deleted too. Your actual audiobook and podcast media files in your library folders are NOT touched.
Node.js security minimum
AudioBookShelf now uses the QuickBox security minimum on Node.js 22 rather than the older Node.js 20 runtime. The same isolated runtime builds the client and starts the service. The current QuickBox policy sets 22.23.4 as the minimum for Node.js 22. This is a security minimum, not a permanent version pin; later QuickBox updates can raise it.
QuickBox checks existing app copies during qb update quickbox and attempts to raise copies below the security minimum. An app update also applies the policy. Check the app-specific copy as the affected account:
sudo -u username /opt/username/lib/nodejs/Audiobookshelf/.venv/bin/node --versionThe shell’s node --version may report a different system or user-managed installation. It does not identify the copy QuickBox provisions for AudioBookShelf. Do not downgrade Node.js to match an older example or replace the system Node.js package as a workaround.
Troubleshooting
”The Node.js security floor list cannot be read”
If an install or update reports The Node., QuickBox could not validate its security policy. The file can exist and still fail validation: unreadable contents, a malformed entry, or a missing min= entry all cause this error. The application step stops rather than choosing an unverified Node.js version.
Run these read-only checks as the server administrator:
ls -l /opt/quickbox/config/software/node-security-floor
sed -n 'l' /opt/quickbox/config/software/node-security-floorThe list contains a min=x. entry and release-line entries such as 22=22.; each numbered key must match the major in its version. Comments and blank lines are allowed. The sed output also exposes unexpected characters and line endings, so send its exact output rather than only a directory listing.
If QuickBox has not finished updating, complete qb update quickbox first and retain any update errors. If that succeeds but this error persists, send support the two checks above, the exact failing command, OS and QuickBox versions, and the relevant package-log excerpt. Retry qb update audiobookshelf -u username only after the policy issue has been resolved; use the install command instead for an installation that never completed.
Do not create or edit the policy file manually or bypass the check.
Node.js security update could not finish
If the QuickBox update says the app still runs a version below the security floor, the attempted move failed and the old runtime may still be in use. Resolve the logged failure, then retry qb update audiobookshelf -u username. Keep any further error output for support.
If the update specifically says audiobookshelf@username. could not restart after replacing Node.js, inspect its journal, then run systemctl restart audiobookshelf@username. Confirm the app opens from the App Dashboard after the restart. The version command above checks the copy on disk, so it alone does not prove a previously running process switched to the new binary.
A restore-failed warning means the app may not start. Do not delete recovery directories or use reinstall as the first repair.
Install or update seems stuck
Dependency installation and client generation can take several minutes. Read the build log before cancelling the operation:
tail -n 200 /opt/quickbox/logs/audiobookshelf.log
df -h /opt /home
df -i /opt /home
free -hIf the operation exits with a resource or build error, address that error before retrying. Do not run a second package operation while the first is still building.
Service will not start or the health check times out
Replace username with the affected account and run these read-only checks as the server administrator:
systemctl status audiobookshelf@username --no-pager
journalctl -u audiobookshelf@username -n 100 --no-pager
sudo -u username /opt/username/lib/nodejs/Audiobookshelf/.venv/bin/node --version
ls -l /opt/username/audiobookshelf/client/dist/index.html
ls -ld /home/username/.config/audiobookshelf/configCheck the Node.js security minimum for the expected runtime. A missing client artifact or SQLite module error points to an incomplete dependency/client build; a permission error under the state tree needs attention to that exact path. Back up your library state, resolve the logged cause, then retry qb update audiobookshelf -u username.
On first start, the app may fetch its SQLite extension and, when the system FFmpeg is too old, its own FFmpeg. A health-check failure can therefore require checking the journal for a download error as well as a service crash. An active service alone does not prove the page works; open AudioBookShelf from the App Dashboard and confirm your library loads.
Update rebuilds the runtime, server dependencies, and client without removing the separate state tree. Reinstall removes that state tree.
Blank page or missing assets after switching URLs
The client and server must use the same serving base. Check the selected base and generated client:
cat /home/username/.config/audiobookshelf/.base_path
grep -E '^(HOST|PORT|ROUTER_BASE_PATH)=' /opt/username/audiobookshelf/env.conf
ls -l /opt/username/audiobookshelf/client/dist/index.html
nginx -tA marker of / means subdomain mode; the default subpath is /. If the switch was interrupted, run qb update audiobookshelf -u username to regenerate the client using the saved serving base. If the marker and active URL disagree, share the evidence with support before manually editing them.
Forgot the admin password
QuickBox does not manage AudioBookShelf’s app accounts. If another administrator can sign in, use that account to reset the password in Settings → Users.
Copy a backup out of .Quick before attempting database recovery; reinstall deletes accounts, listening progress and the backup folder.
What to send support
Include the exact failing command, OS and QuickBox versions, runtime check above, journal, and the relevant excerpt of /. Redact account tokens, credentials, and private URLs. Do not attach the database or the entire state tree to a public discussion.
Best practices
Do
- Choose a strong password for the root account you create on first run — the login page is reachable by anyone who can reach your server
- Take a Config Only backup regularly, from the Application Backups tab in the Asset Management Center or with
qb manage software -o backup, since the database holds your accounts and progress - Use
qb update audiobookshelf -u usernamefor updates — it backs up the database and rebuilds the client with the correct serving base - Use the official iOS and Android apps for on-the-go listening with progress sync
- Keep an eye on free disk space — cover art and cached metadata under
metadata/grow with your library
Don't
- Don't run
qb remove audiobookshelfbefore copying your backups out of.Quick— it permanently wipes your database, users, progress, and the backup folderBox - Don't edit the port in
env.by hand — nginx and the QuickBox database must agree with it, and QuickBox manages all three togetherconf - Don't delete the
.base_pathmarker in the state tree — updates use it to rebuild the web client for the right URL - Don't install AudioBookShelf from apt or Docker alongside the QuickBox package — they will fight over ports and data paths
FAQ
Resources
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.
- Dedicated Support
- Feature Previews
- Community Configs
- Active Discussions