Reference

Configuration

Tome is configured entirely through environment variables. None are strictly required — even TOME_SECRET_KEY is auto-generated to /data/secret.key on first boot if you don't set one. Everything else has a sensible default.

Reading time —

Quick reference

Variable	Default	Purpose
`TOME_SECRET_KEY`	auto-generated	JWT signing key
`TOME_DATA_DIR`	`/data`	SQLite DB, covers, secret key
`TOME_LIBRARY_DIR`	`/books`	Ebook library root
`TOME_INCOMING_DIR`	`/bindery`	Inbox for new files
`TOME_PORT`	`8080`	HTTP listen port
`TOME_PUBLIC_URL`	—	Canonical public origin (e.g. `https://tome.example.org`) — pin it behind a reverse proxy so the KOReader plugin bakes the correct `https://` URL
`TOME_HARDCOVER_TOKEN`	—	Hardcover API token (optional)
`TOME_HARDCOVER_SYNC_ENABLED`	`true`	Kill switch for per-user Hardcover sync (the token above is metadata-only)
`TOME_GOOGLE_BOOKS_KEY`	—	Google Books API key — your own quota instead of the shared anonymous pool (fixes 403/429 on busy fetch days; recommended for non-English catalogues)
`TOME_RELEASE_DETECTION`	`false`	Follow series + new-volume alerts (needs the Hardcover token) — see Wishlist
`TOME_RELEASE_CHECK_INTERVAL`	`86400`	Seconds between release checks
`TOME_AUTO_IMPORT`	`false`	Auto-ingest from Bindery
`TOME_AUTO_IMPORT_INTERVAL`	`300`	Seconds between scans
`TOME_SCAN_WORKERS`	`1`	Parallel scan worker processes (1 = serial)
`TOME_JWT_ALGORITHM`	`HS256`	JWT algorithm
`TOME_JWT_EXPIRE_MINUTES`	`10080`	JWT lifetime (7 days)
`TOME_SMTP_HOST`	—	SMTP server (enables Send to Device)
`TOME_SMTP_PORT`	`587`	SMTP port
`TOME_SMTP_USER`	—	SMTP username
`TOME_SMTP_PASSWORD`	—	SMTP password / app password
`TOME_SMTP_FROM`	`TOME_SMTP_USER`	"From" address
`TOME_SMTP_USE_TLS`	`true`	STARTTLS (port 587)
`TOME_SMTP_USE_SSL`	`false`	Implicit SSL (port 465)
`TOME_SMTP_DAILY_LIMIT`	`50`	Per-user sends/day (0 = unlimited)
`TOME_SEND_TO_KOREADER`	`false`	Enable the Send to KOReader inbox (beta) — queue books to the device, no email

The secret key

TOME_SECRET_KEY signs every JWT and every API token. If unset, Tome generates a cryptographically random 64-byte key on first boot and writes it to <data_dir>/secret.key with mode 0600. Subsequent boots reuse it.

Paths

The three path variables tell Tome where to keep state, where your library lives, and where to pick up incoming files.

TOME_DATA_DIR — SQLite database, cover cache, baked downloads, secret key. Defaults to /data in Docker. Must be persistent across restarts.
TOME_LIBRARY_DIR — your ebook collection. Read-write so Tome can organise files (move into Series/ or Author/ folders). Defaults to /books.
TOME_INCOMING_DIR — the Bindery drop folder. Files appear here, then get reviewed (or auto-imported) into the library. Defaults to /bindery.

Hardcover metadata

TOME_HARDCOVER_TOKEN turns on the Hardcover lookup path during metadata fetch. Hardcover has the best coverage for modern fiction and manga. Grab a free token from hardcover.app/account/api and pass it in.

With no token set, Tome still fetches metadata via Google Books and Open Library — Hardcover just gets skipped.

Library scanning

TOME_SCAN_WORKERS — worker processes for the CPU-bound part of a library scan (metadata extraction + hashing). Default 1 (serial, in-process) — the lowest-RAM option, and already fast, so it suits the modest hardware most self-hosters run on. Set it higher (e.g. your CPU core count) to parallelise large imports on machines with RAM to spare — each worker adds roughly 60–80 MB. Database writes always stay single-process (SQLite is single-writer), so this only speeds up extraction, not the writes.

Auto-import (Bindery)

TOME_AUTO_IMPORT — set to true to ingest files dropped in /bindery on a schedule. Default is false (manual review queue).
TOME_AUTO_IMPORT_INTERVAL — seconds between scans. Default 300 (5 min).

Even with auto-import on, books land marked is_reviewed=false and surface in the "Unreviewed" queue so an admin can sanity-check the detected metadata. See Bindery.

SMTP (Send to Device)

The TOME_SMTP_* variables enable Send to Device — emailing books to e-readers. The feature stays hidden until TOME_SMTP_HOST, TOME_SMTP_USER, and TOME_SMTP_PASSWORD are all set. Credentials live only in the environment, never the database. See the Send to Device page for provider-specific examples (Gmail, Fastmail) and the Kindle approved-sender step.

JWT lifetime

TOME_JWT_EXPIRE_MINUTES sets how long a browser session stays signed in. Default is one week. TOME_JWT_ALGORITHM is the JWS algorithm (default HS256); leave it alone unless you have a very specific reason.