Configuration

Tome is configured entirely through environment variables. None are strictly required — evenTOME_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.

File ownership (PUID / PGID)

Inside the container Tome runs as an unprivileged user. PUID and PGIDset that user's numeric UID and GID (the same convention as LinuxServer.io images), so the bind-mounted /data, /books and /bindery are read and written as the user that owns them on the host. The default is 1000:1000, which is what the image always ran as, so an existing install needs no change.

Set them when the logs show PermissionError on /books or/bindery. On Synology, QNAP and TrueNAS the share ACL is granted to your docker user, not to uid 1000; run id <user> on the host and pass those ids. On Unraid shares are usually 99:100.

On start the container fixes ownership of /data to match, so switchingPUID on an existing install works without a manual chown. It never touches /books or /bindery — those are your files (and may be read-only mounts). If Tome already created files there under the old uid, chown those yourself. Compose files that pass user: "uid:gid" instead still work; in that mode the container cannot fix /data ownership for you.

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 fromhardcover.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. SeeBindery.

SMTP (Send to Device)

The TOME_SMTP_* variables enable Send to Device — emailing books to e-readers. The feature stays hidden untilTOME_SMTP_HOST, TOME_SMTP_USER, and TOME_SMTP_PASSWORD are all set. Credentials live only in the environment, never the database. See theSend 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.

Production checklist