# KoShelf

> Self-hosted web dashboard combining KOReader notes, highlights, and reading statistics with library browsing, in-app reader, calendar, and optional auth.

- **Category:** Ebook Management
- **Licence:** EUPL-1.2
- **Latest version:** 2026.10.1
- **Open source:** oss
- **Languages:** Typescript, Rust
- **Platforms:** Docker Compose, Linux, Home Assistant, Build from Source
- **Tags:** Dashboard, Statistics, Ebooks, Epub, Mobi, Annotations, Reading, Koreader, Self Hosted, Ebook, Fb2, Highlights, Cbz, Statistic, Reaading

## Description

KoShelf is a self-hosted reading companion that reads KOReader metadata — highlights, annotations, reading progress, and statistics — and presents it in a web dashboard. It supports browsing your library with books and comics, viewing and editing metadata and annotations (with writeback to KOReader sidecars), detailed reading statistics with customizable heatmaps and weekly breakdowns, a monthly reading calendar, and a yearly recap with completions and summaries. An in-app reader opens EPUB, FB2, MOBI, and CBZ files with keyboard navigation and inline highlight notes. KoShelf can run as a live server with file watching or generate a complete static site for hosting anywhere. It supports all three KOReader metadata storage modes (adjacent .sdr folders, docsettings, hashdocsettings) and merges statistics from multiple devices. Optional authentication uses a generated password or delegates to trusted reverse proxies like Home Assistant ingress. The project is open source under EUPL-1.2 and built for personal use with daily testing by the author.

## Links

- [Homepage](https://github.com/paviro/KoShelf)
- [Docker](ghcr.io/devtigro/koshelf)
- [Installation Guide](https://github.com/paviro/KoShelf/blob/main/docs/installation.md)
- [Configuration Guide](https://github.com/paviro/KoShelf/blob/main/docs/configuration.md)
- [KoReader Setup](https://github.com/paviro/KoShelf/blob/main/docs/koreader-setup.md)
- [Authentication Guide](https://github.com/paviro/KoShelf/blob/main/docs/authentication.md)
- [Supported Data](https://github.com/paviro/KoShelf/blob/main/docs/supported-data.md)
- [API Reference](https://github.com/paviro/KoShelf/blob/main/docs/API.md)
- [GitHub Repository](https://github.com/paviro/KoShelf)

---
Source: https://selfhost.directory/project/koshelf