bookhoard/docs/user/devices/koreader-setup.md

KOReader Device Setup Guide

This guide will help you set up KOReader on your e-reader device to sync with Bookhoard.

What is KOReader?

KOReader is an open-source e-reader application that supports a wide range of e-reader devices including:

• Kindle devices (Paperwhite, Oasis, Voyage, etc.)
• Kobo devices (Clara, Aura, Nia, etc.)
• PocketBook devices

It also runs on Android tablets and phones, although Bookhoard's dedicated mobile apps (coming later) will be the better option there.

Prerequisites

Before you begin, make sure you have:

• ✅ A Bookhoard instance running and accessible on your network
• ✅ A web browser logged in to your Bookhoard account (for device approval)
• ✅ A KOReader-compatible e-reader device
• ✅ Your device connected to the same Wi-Fi network as your Bookhoard instance

Installing KOReader

Kindle Devices

1. Install KOReader

   • Download the latest KOReader release from koreader.rocks
   • Extract the koreader folder to your Kindle's root directory
   • Safely eject your Kindle from your computer

2. Launch KOReader

   • On your Kindle, go to Home → Settings → Device Options → Personalize Your Kindle
   • Select koreader from the launcher options
   • Alternatively, you can use the linkjail method to access KOReader directly

3. Enable Wi-Fi

   • In KOReader, tap the network icon in the top menu
   • Connect to your Wi-Fi network

Kobo Devices

1. Install KOReader

   • Download the latest KOReader Kobo package from koreader.rocks
   • Copy the koreader folder to your Kobo's .adds/ directory
   • Safely eject your Kobo from your computer

2. Launch KOReader

   • Eject and disconnect your Kobo
   • Kobo will restart and you'll see KOReader as an option
   • Alternatively, create a shortcut on your home screen

3. Enable Wi-Fi

   • In KOReader, tap the network icon
   • Connect to your Wi-Fi network

PocketBook Devices

1. Install KOReader

   • Download the PocketBook version from koreader.rocks
   • Copy to your device and install via the package manager

2. Launch KOReader

   • Open KOReader from your apps menu
   • Enable Wi-Fi in the network settings

Connecting KOReader to Bookhoard

Setup is done on the server: you approve the device from the Bookhoard web interface — no usernames, passwords, or tokens to type on the device.

Step 1: Install the Bookhoard Plugin

1. Clone the Bookhoard KOReader plugin
2. Copy it to your KOReader plugins/ directory
3. Restart KOReader

Step 2: Point the Plugin at Your Server

1. Open KOReader, tap the wrench icon at the top

2. Find and tap Bookhoard sync

3. Tap Server URL, enter your server address, then tap OK:

   http://YOUR_COMPUTER_IP:8765
   

   Use your server's LAN IP (or domain if you have one configured).

Step 3: Approve the Device in Bookhoard

1. On your computer or phone, open Bookhoard and go to the Devices page (sidebar navigation)
2. Refresh the page — your device appears under Pending Device Registrations
3. Click Approve to connect the device

Once approved, the plugin picks up its credentials automatically — reading progress sync and OPDS catalog access are set up automatically. No further configuration is needed.

Note: Pending registrations expire after 5 minutes. If yours expires, just re-run the sync from the plugin menu and approve again.

Auth Token (Advanced)

The Devices page shows each KOReader device's Auth Token. You normally never need it (the plugin receives it automatically during approval), but it can be re-entered manually in the plugin settings if you're moving a setup between devices or debugging.

What Syncs

Once connected, the following sync automatically in both directions between KOReader and Bookhoard (web and other devices):

• Reading position — percentage, chapter, and EPUB CFI where available
• Bookmarks
• Highlights — including highlight colors, mapped between the web and KOReader palettes
• Notes — standalone and attached to highlights

Books are matched automatically using UUIDs, file hashes (SHA-256, format-aware so converted files still match), file aliases, and title/author fallback. If a book can't be matched, it shows up under the device's Unlinked Books in Bookhoard, where you can link it manually.

OPDS Wireless Book Delivery

Once your device is approved, the plugin also registers Bookhoard's OPDS catalog, so you can browse and download books wirelessly — no USB cable needed.

Browse and Download Books

1. In KOReader, open the OPDS catalog list and tap Bookhoard
2. Browse your library: all books, collections, and recent additions
3. Tap a book to see details and Download it

Supported Formats

• EPUB: Standard ebook format
• KEPUB: Kobo-optimized format
• PDF: Fixed-layout documents
• CBZ: Comic book archives

Books downloaded via OPDS are automatically matched to your library, so their progress syncs from the first page.

Troubleshooting

Pending Registration Never Appears

Problem: You entered the Server URL, but no pending registration shows in Bookhoard

Solutions:

1. Verify the Server URL is correct (no trailing path — just the base address)
2. Make sure KOReader is connected to Wi-Fi
3. Check the Bookhoard server is reachable from the device's network
4. Registrations expire after 5 minutes — re-run the sync and approve quickly

Connection Refused

Problem: "Connection refused" error on the device

Solutions:

• Verify Bookhoard is running
• Check the server address and port (default 8765)
• Ensure the device is on the same Wi-Fi network as the server
• Use the server's LAN IP instead of localhost

Sync Not Working After Approval

Problem: Device shows as approved but changes don't appear in Bookhoard

Solutions:

• Trigger a manual sync from the plugin menu
• Check the device shows as enabled on the Devices page (open its settings from the icon next to the device)
• Verify the book appears as an unlinked book for the device and link it if needed
• Check Bookhoard server logs for errors

Conflicts Detected

Problem: Sync conflicts when reading the same book on multiple devices

Solutions:

1. Open the book's detail page and click Sync Progress, or open the Conflicts page (/conflicts)
2. Review the progress reported by each device
3. Choose which device's progress to keep

Security Best Practices

1. Use HTTPS: If exposing Bookhoard beyond your LAN, configure SSL/TLS
2. Network Security: Ensure your Wi-Fi network is secure (WPA2/WPA3)
3. Device Authorization: Only approve pending registrations you initiated
4. Revoke lost devices: Remove devices you no longer use from the Devices page

Additional Resources

• KOReader Documentation
• KOReader Forum
• Bookhoard Universal Sync Guide
• Bookhoard KOReader Plugin

---

Last Updated: August 2026 Bookhoard Version: 1.0