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.

Quick reference

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.

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.

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.

Production checklist