# 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](https://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](https://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](https://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](https://git.linuxhg.com/Bookhoard/bookhoard.koplugin)
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](https://github.com/koreader/koreader)
- [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=271)
- [Bookhoard Universal Sync Guide](../sync-guide.md)
- [Bookhoard KOReader Plugin](https://git.linuxhg.com/Bookhoard/bookhoard.koplugin)

---

**Last Updated**: August 2026
**Bookhoard Version**: 1.0