What is ShelfBridge?

ShelfBridge is a self-hosted synchronization tool that connects your Audiobookshelf server to Hardcover, automatically syncing reading progress for audiobooks and ebooks. It supports multiple users from a single instance, flexible configuration via environment variables or YAML, library include/exclude filtering, progress regression protection, and intelligent 3-tier book matching using ASIN, ISBN, or title/author fuzzy matching. The application runs as a scheduled background job (default daily at 3 AM) and can be deployed via Docker Compose or run directly with Node.js 22/24. It uses an embedded SQLite database (better-sqlite3) for caching and state, requiring no external database server.

Should you self-host ShelfBridge?

ShelfBridge scores 47/100 on selfhost.directory (how scoring works) and ranks #9 of 15 in Audiobook Management. It has 158 GitHub stars.

It shipped 15 stable releases in the past year. The latest, v1.23.13, came out on 10 August 2026. New versions land roughly every 5 days.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is MIT-licensed and written mostly in JavaScript.

Its closest alternative on selfhost.directory is Audiobookshelf (79/100, 14 828 stars). It scores higher overall, so compare the two before you pick. See ShelfBridge vs Audiobookshelf side by side.

Features

Auto-add books to Hardcover
Automatic scheduled sync
CLI Interface
Comprehensive logging
Cross-edition matching
Dry Run Mode
Ebook progress sync
Library filteringRequires YAML configuration; not available via environment variables
Multi-user support
Progress regression protection
Reread detectionRequires YAML configuration
Session-based delayed updates
Smart 3-tier book matching

How to configure ShelfBridge

PGIDGroup ID for container permissions
Group ID for container permissions
PUIDUser ID for container permissions
User ID for container permissions
SHELFBRIDGE_AUDIOBOOKSHELF_RATE_LIMIT600Audiobookshelf API requests per minute
Audiobookshelf API requests per minute
values: 60-1200
SHELFBRIDGE_AUDIOBOOKSHELF_SEMAPHORE5Max concurrent Audiobookshelf API requests
Max concurrent Audiobookshelf API requests
values: 1-10
SHELFBRIDGE_AUTO_ADD_BOOKSfalseAutomatically add books to Hardcover that don't exist
Automatically add books to Hardcover that don't exist
values: true/false
SHELFBRIDGE_DELAYED_UPDATES_ENABLEDfalseEnable session-based delayed updates to reduce API calls
Enable session-based delayed updates to reduce API calls
values: true/false
SHELFBRIDGE_DELAYED_UPDATES_IMMEDIATE_COMPLETIONtrueAlways sync book completion immediately
Always sync book completion immediately
values: true/false
SHELFBRIDGE_DELAYED_UPDATES_MAX_DELAY3600Maximum delay in seconds before forcing sync
Maximum delay in seconds before forcing sync
values: 300-86400
SHELFBRIDGE_DELAYED_UPDATES_SESSION_TIMEOUT900Session timeout in seconds before syncing delayed updates
Session timeout in seconds before syncing delayed updates
values: 60-7200
SHELFBRIDGE_DRY_RUNfalseRun without making actual changes
Run without making actual changes
values: true/false
SHELFBRIDGE_DUMP_FAILED_BOOKStrueCreate error reports for failed books
Create error reports for failed books
values: true/false
SHELFBRIDGE_FORCE_SYNCfalseForce sync even if progress appears unchanged
Force sync even if progress appears unchanged
values: true/false
SHELFBRIDGE_HARDCOVER_RATE_LIMIT55Hardcover API requests per minute
Hardcover API requests per minute
values: 10-60
SHELFBRIDGE_HARDCOVER_SEMAPHORE1Max concurrent Hardcover API requests
Max concurrent Hardcover API requests
values: 1-10
SHELFBRIDGE_MAX_BOOKS_TO_FETCHMaximum books to fetch from Audiobookshelf
Maximum books to fetch from Audiobookshelf
SHELFBRIDGE_MAX_BOOKS_TO_PROCESSLimit books processed per sync
Limit books processed per sync
SHELFBRIDGE_MIN_PROGRESS_THRESHOLD5.0Minimum progress percentage required to sync (0-100)
Minimum progress percentage required to sync (0-100)
values: 0-100
SHELFBRIDGE_PAGE_SIZE100Books per API request
Books per API request
values: 25-200
SHELFBRIDGE_PARALLELtrueEnable parallel processing
Enable parallel processing
values: true/false
SHELFBRIDGE_PREVENT_PROGRESS_REGRESSIONtruePrevent accidental progress regression
Prevent accidental progress regression
values: true/false
SHELFBRIDGE_SYNC_SCHEDULE0 3 * * *Cron schedule for automatic sync
Cron schedule for automatic sync
SHELFBRIDGE_TIMEZONEUTCTimezone for scheduling and logging
Timezone for scheduling and logging
SHELFBRIDGE_USER_0_ABS_TOKENAudiobookshelf API token for primary user
Audiobookshelf API token for primary user
SHELFBRIDGE_USER_0_ABS_URLAudiobookshelf server URL for primary user
Audiobookshelf server URL for primary user
SHELFBRIDGE_USER_0_HARDCOVER_TOKENHardcover API token for primary user
Hardcover API token for primary user
SHELFBRIDGE_USER_0_IDUser identifier for primary user
User identifier for primary user
SHELFBRIDGE_WORKERS3Number of parallel workers for API requests
Number of parallel workers for API requests
values: 1-10