Skip to content

1. Get Started

Jump to bottom
Jimmy Pautz edited this page Aug 25, 2026 · 19 revisions

Installation & Quick Start Guide

This guide details how to install, update, and configure the X-Ray plugin on various devices running KOReader.

Requirements

  • KOReader version 2024.01 or newer.
  • An active Wi-Fi / Internet connection on your device during initial setup and AI data fetching.
  • An API key from a supported AI provider (Google Gemini [free tier recommended], OpenAI, Anthropic Claude, DeepSeek, or any OpenAI-compatible provider like OpenRouter).

Method 1: Install via Storefront (Recommended)

If you use the Storefront plugin manager for KOReader, you can install and update X-Ray directly on your device without connecting to a computer:

  1. Open KOReader on your device.
  2. Open the Tools menu (wrench icon / menu) and launch Storefront.
  3. Search for or browse to X-Ray in the plugin list.
  4. Tap Install.
  5. Restart KOReader when prompted.

Tip

Storefront will automatically check for new X-Ray releases and allow seamless, one-tap updates directly on your e-reader.

Method 2: Manual Installation

If you prefer to install the plugin manually via USB or file transfer:

Step 1: Download the Plugin Archive

  1. Visit the X-Ray Releases page.
  2. Download the latest xray.koplugin.zip release archive.

Step 2: Transfer to Your Device

Unpack xray.koplugin.zip into the plugins/ directory of your KOReader installation. The resulting folder structure must be:

[koreader-directory]/plugins/xray.koplugin/

Common Device Installation Paths

Device / OS KOReader Directory Path Full Plugin Destination
Kindle (USB) koreader/ or /mnt/us/koreader/ /mnt/us/koreader/plugins/xray.koplugin/
Kobo (USB) .kobo/koreader/ (show hidden folders) .kobo/koreader/plugins/xray.koplugin/
Android sdcard/koreader/ or Android/data/org.koreader.launcher/files/ /sdcard/koreader/plugins/xray.koplugin/
PocketBook system/koreader/ (show hidden folders) system/koreader/plugins/xray.koplugin/
Linux ~/.config/koreader/ ~/.config/koreader/plugins/xray.koplugin/
macOS ~/Library/Application Support/koreader/ ~/Library/Application Support/koreader/plugins/xray.koplugin/
Windows %APPDATA%\koreader\ %APPDATA%\koreader\plugins\xray.koplugin\

Important

Make sure the folder is extracted as xray.koplugin directly inside plugins/ (e.g., plugins/xray.koplugin/main.lua). Avoid nested directories such as plugins/xray.koplugin/xray.koplugin/.

Step 3: Restart KOReader

Exit and restart KOReader (or reboot your device) so the newly installed plugin is loaded.

Updating the Plugin

  • Via Storefront: Open Storefront on your device, check the updates section, and tap Update.
  • Manual Update: Download the newest xray.koplugin.zip and replace the existing xray.koplugin directory on your device.
  • Silent Background Updates: The plugin can also automatically check for new releases once a week in the background and notify you when an update is available.

Note

All fetched book X-Ray data and user configurations are stored safely in KOReader's persistent settings directory and will not be lost when updating the plugin.

Quick Configuration & Setup

Once installed, follow these 3 quick steps to get X-Ray running on your books:

1. Get an API Key

X-Ray requires an API key from a supported AI provider to analyze book text. We recommend Google Gemini for its generous free tier:

  • Google Gemini (Recommended / Free Tier): Grab a free key at Google AI Studio.
  • Other Supported Providers: OpenAI, DeepSeek, Anthropic Claude, and OpenRouter / Custom APIs.

Tip

For direct links and signup guides for all providers, check out API Key Setup Options.

2. Enter Your API Key

The fastest way to add your key without typing on an E-Ink keyboard is using Phone / PC Quick Setup:

  1. In KOReader, open any book and go to Tools Menu → X-Ray → Settings → AI Settings → API Keys & Providers → Set Key from Phone / PC ▸.
  2. Scan the on-screen QR code with your phone (or visit the link on your PC).
  3. Paste your key in your browser and tap Send Encrypted Key to E-Reader.

Note

Prefer offline or direct entry? X-Ray supports 5 different setup methods, including offline local Wi-Fi transfer, USB text file drop (xray_key.txt), configuration files (xray_config.lua), and on-screen keyboard input. See the full API Key Setup Options guide for walkthroughs of every method.

3. Fetch Data for Your First Book

  1. With any book open, navigate to Tools Menu → X-Ray → Fetch X-Ray Data.
  2. Wait 30–60 seconds for the initial extraction.
  3. A summary dialog will appear once complete. All data is saved locally on your device—no active internet connection is needed to browse X-Ray data while reading!

Next Steps

Explore what you can do with X-Ray:

  • API Key Setup Options — All 5 ways to enter your API key: Phone/PC QR code, Local Wi-Fi, file drop, config file, and on-screen keyboard.
  • Core Content & Features — Explore Characters, Plot Timelines, Glossaries, Series Recaps, and Unit Conversions.
  • Lookups & Navigation — Use inline footnote popups, gesture shortcuts, and mention scans.
  • AI Providers & Models — Compare AI providers, models, fallback models, and reasoning effort.
  • Spoiler Protection — Learn how spoiler-free filtering keeps twists safe.
  • Fetching Data — Learn about background auto-fetching, target fetching, and full book analysis.

Clone this wiki locally