Skip to content
Back to search

tome

Self-hosted ebook library server with built-in reader, KOReader sync, OPDS feed, and reading stats. Single Docker image.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bndct-devops/tome with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bndct-devops/tome'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bndct-devops--tome/badge.svg)](/listings/bndct-devops--tome)

HTML

<a href="/listings/bndct-devops--tome"><img src="/api/listings/bndct-devops--tome/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

docker run -d \
  --name tome \
  --restart unless-stopped \
  -p 8080:8080 \
  -v ./data:/data \
  -v ./books:/books \
  -v ./bindery:/bindery \
  ghcr.io/bndct-devops/tome:latest

Open `http://localhost:8080` and follow the setup wizard to create your admin account.

Or with Docker Compose -- the canonical `docker-compose.yml` in this repo is portable; clone and `docker compose up -d`. See `docs/examples/` for setups specific to Unraid and similar.

Try it in 60 seconds

Want to kick the tires before committing it to your homelab? This installer spins Tome up in a fresh `~/Tome` folder on a free port and prints the URL -- all it needs is Docker installed and running:

curl -fsSL https://tome.bndct.sh/install.sh | bash

Upload a book, click around, decide if it's for you. It uses a **fresh, empty** `~/Tome/books`, so nothing in your real library is touched. (It's a plain shell script -- read it first with `... | less` if you like.)

Didn't click? Remove every trace -- container, image, and folder:

cd ~/Tome && docker compose down             # stop + remove the container
docker rmi ghcr.io/bndct-devops/tome:latest  # drop the image
rm -rf ~/Tome                                 # delete data + the test books folder

Did click? **Don't run it on your laptop long-term.** Move `~/Tome` to an always-on box (NAS, mini-PC, that spare Pi) and point the `books` volume at your real library. A sleeping laptop is a poor host for KOReader sync and OPDS -- a box that's always up is where Tome belongs.

Volumes

| Mount | Purpose | |-------|---------| | `/data` | SQLite database and cover cache | | `/books` | Ebook library (read-only is fine) | | `/bindery` | Incoming folder for new books |

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | `PUID` / `PGID` | No | `1000` / `1000` | Host UID/GID the container runs as. Set to the owner of your mounts (Synology/QNAP/TrueNAS: your docker user; Unraid: `99`/`100`) | | `TOME_SECRET_KEY` | Yes | -- | JWT signing secret | | `TOME_DATA_DIR` | No | `/data` | DB and cover cache | | `TOME_LIBRARY_DIR` | No | `/books` | Library root | | `TOME_INCOMING_DIR` | No | `/bindery` | Bindery folder | | `TOME_PORT` | No | `8080` | HTTP port | | `TOME_PUBLIC_URL` | No | -- | Canonical public origin (e.g. `https://tome.example.org`). Pin this behind a reverse proxy so the KOReader plugin is baked with the correct `https://` URL | | `TOME_HARDCOVER_TOKEN` | No | -- | [Hardcover](https://hardcover.app) API token for metadata | | `TOME_AUTO_IMPORT` | No | `false` | Auto-import files from the bindery on a schedule | | `TOME_AUTO_IMPORT_INTERVAL` | No | `300` | Seconds between auto-import scans | | `TOME_SCAN_WORKERS` | No | `1` | Parallel scan workers (>1 = multi-process; ~60–80 MB each) | | `TOME_KOSYNC_POSITION_BRIDGE` | No | `false` | Experimental: let TomeSync plugin devices pick up progress pushed by third-party KOSync clients (read-only bridge) |

Secrets can also be read from a file (Docker/Kubernetes secrets): `TOME_SECRET_KEY`, `TOME_HARDCOVER_TOKEN`, `TOME_GOOGLE_BOOKS_KEY`, `TOME_SMTP_USER`, `TOME_SMTP_PASSWORD` and `TOME_OIDC_CLIENT_SECRET` each accept a `_FILE` variant, e.g. `TOME_SECRET_KEY_FILE=/run/secrets/tome_secret_key`. Set one or the other, not both.

Supported Formats

| Format | Reader | Notes | |--------|--------|-------| | EPUB | Text reader | CFI position tracking | | CBZ | Comic reader | Streaming page delivery | | CBR | Comic reader | Auto-repacked to ZIP | | PDF | Browser viewer | Served directly |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 252 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/screenshots/hero.gif" alt="Tome — browsing the library, reading stats, and KOReader sync in action" />
  3. </p>
  4. # Tome
  5. [![Build](https://github.com/bndct-devops/tome/actions/workflows/docker.yml/badge.svg)](https://github.com/bndct-devops/tome/actions/workflows/docker.yml)
  6. [![Release](https://img.shields.io/github/v/release/bndct-devops/tome?include_prereleases&sort=semver)](https://github.com/bndct-devops/tome/releases)
  7. [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
  8. [![Container](https://img.shields.io/badge/ghcr.io-bndct--devops%2Ftome-blue?logo=docker)](https://github.com/bndct-devops/tome/pkgs/container/tome)
  9. A self-hosted ebook library server that knows how you read -- not just what you own.
  10. Most library servers stop at file management. Tome connects to your e-reader via a custom [KOReader](https://koreader.rocks) plugin, records every reading session with page-level granularity, syncs positions bidirectionally between device and browser, and turns all of it into stats that get sharper the more you read.
  11. Built with FastAPI, React, and SQLite. Ships as a single Docker image.
  12. > **[Documentation](https://tome.bndct.sh/docs)** · **[Why Tome?](https://tome.bndct.sh/why)** · **[Blog](https://tome.bndct.sh/blog)**
  13. ## Highlights
  14. - **TomeSync** -- custom KOReader plugin records reading sessions, syncs positions bidirectionally (device to web, web to device), and works fully offline. This is what makes Tome different. Use a current KOReader release (v2024.07 or newer for all features). [Details](docs/koreader-plugin.md)
  15. - **Reading stats** -- session tracking, streaks, time-of-day heatmaps, reading pace, completion estimates, genre trends, monthly comparisons, and per-book breakdowns -- all powered by real session data from your e-reader
  16. - **Calendar** -- every month of your reading as a calendar: the books you had open each day as chips, a card for any day with what you read, how far you got, your pace, and when you read. [Details](https://tome.bndct.sh/docs/calendar)
  17. - **Hardcover sync** -- push your ratings (half-stars included), progress, and finish dates to your [Hardcover](https://hardcover.app) profile. One-way, opt-in, per-user; nothing is ever deleted on Hardcover. If you don't know Hardcover yet: it's the indie, ad-free Goodreads alternative with a public API -- well worth a look even without Tome. [Details](https://tome.bndct.sh/docs/hardcover)
  18. - **Metadata from 3 sources** -- fetch and compare metadata from [Hardcover](https://hardcover.app), Google Books, and OpenLibrary with a side-by-side diff UI
  19. - **Built-in reader** -- EPUBs, manga (CBZ/CBR), and PDFs render directly in the browser. Two-page spread, RTL mode, webtoon scroll, pinch-to-zoom on mobile. [Details](docs/reader.md)
  20. - **Bindery** -- an inbox for incoming books. Drop files in a folder, review pre-filled metadata, accept into your library. Optional auto-import on a schedule. [Details](docs/bindery-deployment.md)
  21. - **Scribe** -- a Claude Code Skill for conversational batch ingest, metadata refresh, series-wide audits, and series-level annotation (arc breakdowns, publication status). Uses API tokens for auth and talks to Tome over HTTP. [Details](docs/scribe.md)
  22. - **OPDS feed** -- browse and download from KOReader, Panels, Chunky, or any OPDS client
  23. - **SSO (OIDC)** -- optional single sign-on against any OpenID Connect provider (Pocket ID, Authelia, Authentik, Keycloak, …) with group-to-role mapping and account linking. Local login always stays. [Details](docs/sso.md)
  24. - **Themes** -- 3 built-in (light, dark, amber) plus fully custom themes via 10-value hex palette
  25. Plus: series browsing with story arcs and publication status, bulk operations, libraries with icons, shelves (saved filters), Quick Connect (6-char code sign-in), OPDS PINs (e-ink-friendly passwords), role-based access control, per-user book visibility, user-level API tokens, audit logging, and a bulk import script. [Full feature list](docs/features.md)
  26. ## How is Tome different?
  27. There are several self-hosted ebook tools — here's where Tome sits.
  28. | | Tome | Calibre-Web | Komga | Kavita |
  29. |---|---|---|---|---|
  30. | **Reading session tracking** (time, pace, streaks from your e-reader) | ✅ via TomeSync plugin | ❌ | ❌ | ❌ |
  31. | **Bidirectional position sync** with KOReader | ✅ | partial (KOSync) | ❌ | partial |
  32. | **Built-in EPUB + manga reader** | ✅ | ✅ | manga only | ✅ |
  33. | **Stats / reading insights** | ✅ rich | minimal | minimal | minimal |
  34. | **Single-binary deploy** | ✅ Docker, FastAPI + SQLite | requires Calibre install | ✅ | ✅ |
  35. | **Comics & novels in one place** | ✅ | EPUB-focused | comics-focused | ✅ |
  36. | **Maturity** | v1.0 | mature, dated UI | mature | mature |
  37. Pick **Calibre-Web** if you want the largest ecosystem and don't mind the dated UI. **Komga** if you're comics/manga-only. **Kavita** if you want a featureful all-rounder. **Tome** if reading-session tracking and KOReader integration are what you actually want — that's what it's built around.
  38. ![Home](docs/screenshots/home.png)
  39. *Home is built around the book you are reading: progress, Resume, the other books in progress, what comes next in the series, and four bare numbers.*
  40. ![Library](docs/screenshots/dashboard.png)
  41. *Filter, sort, group by series and browse your library. Bulk select for metadata edits, library assignment, or export.*
  42. ![Quick look](docs/screenshots/quick-look.png)
  43. *A quick look opens from any cover: description, progress, reading time, Read and Open page, without leaving where you are.*
  44. ![Series Detail](docs/screenshots/series-detail.png)
  45. *Drill into a series to see every volume, track progress per book, and pick up where you stopped.*
  46. ![Book Detail](docs/screenshots/book-detail.png)
  47. *Full metadata view with cover, description, reading stats per book and one-click reading.*
  48. ![Series](docs/screenshots/series.png)
  49. *All your series at a glance with volume counts and descriptions.*
  50. ![Stats](docs/screenshots/stats.png)
  51. *Reading activity, streaks, session history, and time-of-day patterns on boards you can rearrange.*
  52. ![Calendar](docs/screenshots/calendar.png)
  53. *A month of reading as a calendar, with a card for any day you pick.*
  54. ![Highlighting in KOReader](docs/screenshots/tomesync-koreader-highlight.png)
  55. *Highlight and annotate on your e-reader…*
  56. ![Highlights in Tome](docs/screenshots/koreader-highlights.png)
  57. *…and they sync to Tome via the TomeSync plugin, collected per book with the text, your note, and the chapter.*
  58. ### Mobile
  59. Tome works as a PWA on mobile. Pin it to your home screen for a native app feel.
  60. | | | | | |
  61. |---|---|---|---|---|
  62. | ![Home](docs/screenshots/mobile-home.png) | ![Stats](docs/screenshots/mobile-stats.png) | ![Sidebar](docs/screenshots/mobile-sidebar.png) | ![Series](docs/screenshots/mobile-series.png) | ![Reader](docs/screenshots/mobile-reader.png) |
  63. ### iPhone
  64. Tome Reader is a native iPhone app for your Tome: pair with a QR code from
  65. Settings → Quick Connect, browse the library and series, read EPUB and comics
  66. offline, and keep progress and stats in sync. It is in **free beta until
  67. 31 December 2026** — [join it on TestFlight](https://testflight.apple.com/join/JrHyntNU).
  68. The app is closed source and entirely optional. Tome never requires it, and
  69. everything it does goes through the same public API any other client can use.
  70. Feedback on the app goes to [Discussions > Tome Reader (iOS)](https://github.com/bndct-devops/tome/discussions/categories/tome-reader-ios).
  71. | | | | | |
  72. |---|---|---|---|---|
  73. | ![Home](docs/screenshots/ios-home.png) | ![Library](docs/screenshots/ios-library.png) | ![Book](docs/screenshots/ios-book.png) | ![Reader](docs/screenshots/ios-reader.png) | ![Stats](docs/screenshots/ios-stats.png) |
  74. ## Quick Start
  75. ```bash
  76. docker run -d \
  77. --name tome \
  78. --restart unless-stopped \
  79. -p 8080:8080 \
  80. -v ./data:/data \
  81. -v ./books:/books \
  82. -v ./bindery:/bindery \
  83. ghcr.io/bndct-devops/tome:latest
  84. ```
  85. Open `http://localhost:8080` and follow the setup wizard to create your admin account.
  86. Or with Docker Compose -- the canonical `docker-compose.yml` in this repo is portable; clone and `docker compose up -d`. See `docs/examples/` for setups specific to Unraid and similar.
  87. ### Try it in 60 seconds
  88. Want to kick the tires before committing it to your homelab? This installer spins Tome up in a fresh `~/Tome` folder on a free port and prints the URL -- all it needs is Docker installed and running:
  89. ```bash
  90. curl -fsSL https://tome.bndct.sh/install.sh | bash
  91. ```
  92. Upload a book, click around, decide if it's for you. It uses a **fresh, empty** `~/Tome/books`, so nothing in your real library is touched. (It's a plain shell script -- read it first with `... | less` if you like.)
  93. Didn't click? Remove every trace -- container, image, and folder:
  94. ```bash
  95. cd ~/Tome && docker compose down # stop + remove the container
  96. docker rmi ghcr.io/bndct-devops/tome:latest # drop the image
  97. rm -rf ~/Tome # delete data + the test books folder
  98. ```
  99. Did click? **Don't run it on your laptop long-term.** Move `~/Tome` to an always-on box (NAS, mini-PC, that spare Pi) and point the `books` volume at your real library. A sleeping laptop is a poor host for KOReader sync and OPDS -- a box that's always up is where Tome belongs.
  100. ### Volumes
  101. | Mount | Purpose |
  102. |-------|---------|
  103. | `/data` | SQLite database and cover cache |
  104. | `/books` | Ebook library (read-only is fine) |
  105. | `/bindery` | Incoming folder for new books |
  106. ### Environment Variables
  107. | Variable | Required | Default | Description |
  108. |----------|----------|---------|-------------|
  109. | `PUID` / `PGID` | No | `1000` / `1000` | Host UID/GID the container runs as. Set to the owner of your mounts (Synology/QNAP/TrueNAS: your docker user; Unraid: `99`/`100`) |
  110. | `TOME_SECRET_KEY` | Yes | -- | JWT signing secret |
  111. | `TOME_DATA_DIR` | No | `/data` | DB and cover cache |
  112. | `TOME_LIBRARY_DIR` | No | `/books` | Library root |
  113. | `TOME_INCOMING_DIR` | No | `/bindery` | Bindery folder |
  114. | `TOME_PORT` | No | `8080` | HTTP port |
  115. | `TOME_PUBLIC_URL` | No | -- | Canonical public origin (e.g. `https://tome.example.org`). Pin this behind a reverse proxy so the KOReader plugin is baked with the correct `https://` URL |
  116. | `TOME_HARDCOVER_TOKEN` | No | -- | [Hardcover](https://hardcover.app) API token for metadata |
  117. | `TOME_AUTO_IMPORT` | No | `false` | Auto-import files from the bindery on a schedule |
  118. | `TOME_AUTO_IMPORT_INTERVAL` | No | `300` | Seconds between auto-import scans |
  119. | `TOME_SCAN_WORKERS` | No | `1` | Parallel scan workers (>1 = multi-process; ~60–80 MB each) |
  120. | `TOME_LOG_LEVEL` | No | `INFO` | Level of Tome's own log lines: `DEBUG`, `INFO`, `WARNING` or `ERROR` |
  121. | `TOME_KOSYNC_POSITION_BRIDGE` | No | `false` | Experimental: let TomeSync plugin devices pick up progress pushed by third-party KOSync clients (read-only bridge) |
  122. | `TOME_MAX_UPLOAD_MB` | No | `4096` | Largest upload the server accepts, in MB; a bigger book upload is refused with 413 before it is written to disk. `0` = no limit. Backup restores are not limited |
  123. | `TOME_WEBHOOK_ALLOWED_HOSTS` | No | -- | Comma-separated host names or IPs (e.g. `ntfy.lan,192.168.1.20`) that members' notification channels may reach. Admins' channels may point anywhere; everyone else's must resolve to public internet addresses unless the host is listed here |
  124. | `TOME_CONTENT_SECURITY_POLICY` | No | `on` | Send a Content-Security-Policy with the web interface, which stops script inside a book from running in the reader. `off` drops the header (only if a proxy or setup of yours breaks with it) |
  125. Secrets can also be read from a file (Docker/Kubernetes secrets): `TOME_SECRET_KEY`, `TOME_HARDCOVER_TOKEN`, `TOME_GOOGLE_BOOKS_KEY`, `TOME_SMTP_USER`, `TOME_SMTP_PASSWORD` and `TOME_OIDC_CLIENT_SECRET` each accept a `_FILE` variant, e.g. `TOME_SECRET_KEY_FILE=/run/secrets/tome_secret_key`. Set one or the other, not both.
  126. ### Supported Formats
  127. | Format | Reader | Notes |
  128. |--------|--------|-------|
  129. | EPUB | Text reader | CFI position tracking |
  130. | CBZ | Comic reader | Streaming page delivery |
  131. | CBR | Comic reader | Auto-repacked to ZIP |
  132. | PDF | Browser viewer | Served directly |
  133. ## Development
  134. Requirements: Python 3.12+, Node.js 22.19+
  135. ```bash
  136. ./dev.sh # starts backend :8080 + frontend :5173
  137. ```
  138. | Layer | Technology |
  139. |-------|------------|
  140. | Backend | Python 3.12+ / FastAPI |
  141. | Database | SQLite (WAL) / SQLAlchemy 2.0 |
  142. | Frontend | React 19 / Vite / TypeScript |
  143. | Styling | Tailwind CSS 4 |
  144. | Auth | JWT (python-jose) |
  145. See [CONTRIBUTING.md](CONTRIBUTING.md) for project conventions and PR guidelines.
  146. ## Translating
  147. The web UI is translatable. English is the source and lives in the code;
  148. every other language is a community-maintained catalog under
  149. `frontend/src/locales/<code>/messages.po`, editable with any text editor or
  150. [Poedit](https://poedit.net/). Anything not yet translated falls back to
  151. English, so partial catalogs are fine to ship. To improve a language, fill in
  152. the empty `msgstr` entries and open a pull request; to add one, see
  153. [docs/translating.md](docs/translating.md) for the two-line setup. The
  154. KOReader plugin and this website stay English for now.
  155. ## Documentation
  156. - [Reader](docs/reader.md) -- EPUB, comic/manga reader, keyboard shortcuts, ComicInfo.xml
  157. - [KOReader Plugin](docs/koreader-plugin.md) -- TomeSync setup, sync behavior, offline support
  158. - [Bindery](docs/bindery-deployment.md) -- setting up the incoming book inbox
  159. - [Scribe](docs/scribe.md) -- Claude Code Skill for batch ingest, metadata refresh, and series audits
  160. - [Import Script](docs/import.md) -- bulk importing an existing collection from filenames
  161. - [Features](docs/features.md) -- Quick Connect, OPDS PINs, permissions, themes, API tokens, and more
  162. - [Translating](docs/translating.md) -- improving or adding a UI language
  163. ## Telemetry
  164. Off by default. Admins are asked once whether Tome may send one small anonymous report a month, and the question shows the exact report before you can say yes. Never a title, a name or a hostname. `TOME_TELEMETRY=false` hides the question entirely. What is in the report, how consent works and where it goes: [tome.bndct.sh/docs/telemetry](https://tome.bndct.sh/docs/telemetry). The numbers it produces are public at [tome.bndct.sh/stats](https://tome.bndct.sh/stats).
  165. Separately from telemetry, Tome checks upgrades.bndct.dev once a day for a newer version. Only the version number is sent. `TOME_UPDATE_CHECK=false` turns it off.
  166. ## Questions and feedback
  167. Bugs and concrete feature requests go to [Issues](https://github.com/bndct-devops/tome/issues).
  168. Setup questions, rough ideas and anything else go to [Discussions](https://github.com/bndct-devops/tome/discussions).
  169. ## Supporters
  170. Tome is free and stays free. If it is useful to you, you can say thanks on
  171. [GitHub Sponsors](https://github.com/sponsors/bndct-devops). Nothing in Tome
  172. is locked behind a sponsorship.
  173. Thank you to everyone who supports Tome:
  174. <!-- supporters:start -->
  175. <!-- supporters:end -->
  176. ## Acknowledgements
  177. - [KOReader](https://koreader.rocks) -- the open source e-reader app that Tome's sync plugin and OPDS integration are built for
  178. - [Hardcover](https://hardcover.app) -- the community-run, ad-free book-tracking platform. Its open GraphQL API powers Tome's metadata fetch, series catalogue, release detection, and profile sync -- go give them your shelf
  179. - [foliate-js](https://github.com/johnfactotum/foliate-js) -- the EPUB rendering engine powering Tome's built-in reader
  180. - Substantial portions of Tome were developed in collaboration with [Claude Code](https://claude.ai/code)
  181. ## License
  182. AGPL-3.0 — see [LICENSE](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.