Caliber

Caliber is a fast, local-first web interface for browsing, searching, reading, and downloading books from any Calibre library. It uses cursor pagination and virtualized lists so large collections remain responsive.

Features

• EPUB, PDF, CBZ, and CBR browser readers
• Downloads for every format stored in the library
• OPDS catalog for compatible reading apps
• Full-text search, tag filters, infinite scroll, list/grid views, and reading progress
• Read-only access to Calibre data with a separate writable search/cache snapshot
• Periodic database refresh while the server is running (including SQLite WAL/SHM changes)
• Bun CLI and optional MCP integrations

Quick start

Requires Bun and a Calibre library. Caliber looks for metadata.db in ~/Calibre Library by default.

git clone https://github.com/briansunter/caliber.git
cd caliber
bun install
bun dev

Open http://localhost:3003. On first launch, if the default library is not present, Caliber opens a library setup screen where you can enter the path to a Calibre metadata.db (or its containing library folder). The selection is validated and applied without a restart; it can be changed later in Settings.

For a scripted or headless setup:

CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" bun dev

To run the published app with Bun and open it in your default browser automatically:

bunx caliber-app

When the default ~/Calibre Library/metadata.db exists, the browser opens automatically. If no usable library is found, Caliber stays running and prints the local URL so you can configure one.

Set the library path when it is not in the default location:

CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" bunx caliber-app

Use --no-open or CALIBER_OPEN_BROWSER=false for headless environments.

Caliber binds to 127.0.0.1 by default. If you intentionally expose it on another interface, set CALIBER_HOST and enable the built-in authentication (see Authentication) plus HTTPS; without auth enabled, the username prompt is only a local reading-progress profile, not authentication. When bound to a non-loopback CALIBER_HOST with no CALIBER_BASE_URL, requests with any Host header are accepted (client host names cannot be enumerated), so enable authentication in that configuration.

Configuration

Configuration can be stored in the platform config directory (~/.config/caliber/config.json on macOS/Linux, %APPDATA%\\caliber\\config.json on Windows), set with CALIBER_CONFIG_DIR, or supplied through environment variables. Environment variables take precedence.

Variable	Default	Description
CALIBRE_LIBRARY_PATH	~/Calibre Library	Calibre library directory; CALIBER_LIBRARY_PATH is accepted as an alias
CALIBRE_DB_NAME	metadata.db	Database filename inside the library directory
PORT / CALIBER_PORT	3003	HTTP port
CALIBER_HOST	127.0.0.1	Bind address; keep loopback for a local library
CALIBER_CONFIG_DIR	platform config directory	Caliber cache and config directory
CALIBER_DB_REFRESH_INTERVAL_MS	60000	Database refresh interval, clamped to 5 seconds–1 hour
CALIBER_BASE_URL	request URL	Public URL used in OPDS feeds behind a proxy
CALIBER_TRUST_PROXY	false	Honor forwarded host/protocol headers only when behind a trusted proxy
CALIBER_COOKIE_SECURE	production: true	Add the Secure attribute to the progress cookie
CALIBER_MCP_ENABLED	false	Enable the HTTP MCP endpoint; the standalone stdio server is separate
CALIBER_AUTH_ENABLED	false	Require sign-in for the web app, API, and OPDS feeds (see Authentication)
CALIBER_ALLOW_NOAUTH_ADMIN	unset	Set to 1 to allow authentication setup from the UI while bound to loopback and auth is off
CALIBER_USER_DB_PATH	<config>/users.db	Location for local profile and reading-progress data
PDFINFO_PATH	auto-detected	Optional path to Poppler pdfinfo
PDFTOPPM_PATH	auto-detected	Optional path to Poppler pdftoppm

Copy .env.example as a starting point for a deployment. Caliber copies the source database through SQLite serialization into its cache so live WAL changes are included, then checks the source periodically and rebuilds its FTS snapshot when it changes. It never writes to the Calibre library.

Authentication

Authentication is optional and off by default. For local UI setup, start Caliber with CALIBER_ALLOW_NOAUTH_ADMIN=1 while bound to loopback, then open the Settings page: under Authentication, turn it on and — if no accounts exist yet — create the first account in the same step; you are signed in immediately. The change takes effect without a restart and persists to config.json, and the same panel adds, removes, and re-passwords accounts. When authentication is off, UI management requires a loopback bind and CALIBER_ALLOW_NOAUTH_ADMIN=1. Once authentication is on, signed-in users can manage accounts according to the server configuration.

For configuration-as-code, set CALIBER_AUTH_ENABLED=true (or "authEnabled": true in config.json) to require a username and password for the web app, the JSON API, the OPDS catalog, and the MCP endpoint. The environment variable takes precedence over config.json and disables runtime toggling. When auth is enabled with no accounts yet, the web UI offers to create the first account; that setup screen closes permanently once one user exists. Accounts can also be managed from the CLI:

bun run cli -- user add alice              # hidden password prompt
bun run cli -- user passwd alice           # change a password
bun run cli -- user list
bun run cli -- user remove alice
echo "secret-password" | bun run cli -- user add alice --password-stdin   # scripted

Each signed-in user gets their own reading-progress shelf, and two standard mechanisms are supported:

• Web browser — a login screen starts a server-side session (HttpOnly cookie, 30-day expiry, revocable by signing out).
• OPDS readers and API clients — HTTP Basic Auth with the same credentials, which is what OPDS apps use. Point an OPDS reader at the feed URL (for example http://localhost:3003/opds) and enter your Caliber username and password when prompted.

Accounts live in users.db in the config directory alongside reading progress, never in the Calibre library. Passwords are hashed with argon2id. Failed logins are throttled per username and client. If you expose Caliber beyond localhost, put it behind HTTPS (a reverse proxy with CALIBER_TRUST_PROXY=true and CALIBER_BASE_URL set) so session cookies and Basic credentials are not sent in cleartext.

CLI

bun run cli -- stats
bun run cli -- search --query "sanderson" --limit 10 --table
bun run cli -- download --id 42 --format epub --out book.epub
bun run cli -- --help

Each command initializes the same writable snapshot used by the server, so first-run CLI commands work on a fresh config directory.

MCP

For local AI tool integration over stdio:

bun src/mcp-server.ts

The HTTP /mcp endpoint is disabled by default. Enable it only on a protected local or authenticated network deployment with CALIBER_MCP_ENABLED=true.

REST and HTTP MCP JSON request bodies are limited to 1 MiB, including chunked requests.

API

GET  /api/health
GET  /api/config/library
PUT  /api/config/library
GET  /api/books?cursor=&limit=&sortBy=&sortOrder=&tag=
GET  /api/books/search?q=
GET  /api/books/:id
GET  /api/books/:id/cover
GET  /api/books/:id/thumb
GET  /api/books/:id/download/:format
GET  /api/books/:id/file/:format
GET  /api/books/:id/epub/*
GET  /api/books/:id/pages/:format/manifest
GET  /api/books/:id/pages/:format/:page
GET  /api/stats
GET  /opds
GET  /opds/search?q=

Development and release checks

bun run check       # tests + typecheck + lint + production frontend build
bun test            # test suite only
bun run build       # production frontend bundle

Production and packaged launches build the current frontend sources in memory at startup. JavaScript for EPUB, PDF, and comic readers loads when needed; generated assets use content hashes, and HTML is revalidated. No prebuilt dist/ directory is required. bun run dev retains Bun's hot reloading, while dist/ remains an optional frontend build artifact.

Releases

Release Please runs on pushes to master. It opens a release PR from conventional commits; after that PR is merged, the workflow creates the GitHub release and publishes the caliber-app package to npm.

Configure these GitHub Actions secrets for npm publishing:

• BWS_ACCESS_TOKEN — Bitwarden Secrets Manager access token
• BWS_NPM_TOKEN_SECRET_ID — Bitwarden secret ID containing the npm token

License

MIT