# KoShelf

KoShelf is a self-hosted reading companion that turns your KOReader metadata into a web dashboard, letting you browse your e-book library, review highlights and annotations with star ratings, track reading statistics,. It is open source and self-hosted, installable on Unraid.

Canonical page: https://ourlocalhost.com/app/2971/koshelf

## Description

KoShelf is a self-hosted reading companion that turns your KOReader metadata into a web dashboard, letting you browse your e-book library, review highlights and annotations with star ratings, track reading statistics, and read EPUB, FB2, MOBI, and CBZ files directly in the browser.

## Platform availability

Available on 1 of 10 platforms: Unraid.

## Health score

53/100 (Fair), based on 4 of 5 factors.
- Maintained: 81 (last commit 37 days ago)
- Popular: 48 (255 GitHub stars)
- Easy to install: 35 (1 install platform, install notes, Docker image)
- Security check: 20 (1 serious finding, CI, tests)

## Security check

1 serious finding: Uses zip 9.0.3, which has a known critical vulnerability.
Automated checks on commit 5b74f61, 5 Nov 2026. Not an audit.

## Links

- GitHub: https://github.com/paviro/KoShelf
- Unraid: https://ca.unraid.net/apps/koshelf-0gt4bdp1d7j4td?q=koshelf

## Common questions

### How do I run KoShelf in Docker?

Use the community-maintained koshelf-docker image. The installation guide includes a sample docker-compose.yml to start it.

### Can KoShelf be placed behind a reverse proxy?

Yes, server mode provides a built-in web server with live file watching for use with a reverse proxy.

### Does KoShelf support login authentication?

Server mode supports optional password protection with session-based auth, login rate limiting, password rotation, and session management.

### Can edits made in KoShelf sync back to KOReader?

Metadata writeback is opt-in in serve mode and syncs annotations, review notes, ratings, and reading status back to KOReader sidecar files.

### Can I host KoShelf as a static website?

It can generate a complete static website that can be hosted anywhere.

### How do I enable original file downloads?

Enable the --include-files flag so original item files can be downloaded from item detail pages, including static exports.

---
Source: Our Local Host (https://ourlocalhost.com/app/2971/koshelf), the self-hosted and open-source app directory.
