---
title: KOReader WireGuard Plugin
tabTitle: KOReader WireGuard Plugin
showOnCv: false
type: Personal
abstract: A KOReader plugin that adds WireGuard VPN support to e-readers, letting me reach my home Calibre library from anywhere without exposing it to the internet.

content:
  - src: cover
    filetype: .webp
    subtitle: The config picker (left) and status screen (right) of the plugin on a Kobo Clara Colour.

pdfFiles: []

quickLinks:
  - kind: github
    url: https://github.com/wtb04/wireguard.koplugin

tags:
  - KOReader
  - Lua
  - WireGuard
  - Kobo
  - Cross-compilation
  - Tooling

---
I recently got back into reading and, being a tech enthusiast, that more or less instantly translated into "I need an e-reader". I have always been curious about e-ink and wanted to see how much the technology had matured over the last few years. Looking around, the current e-reader space turned out to be quite divided and dominated by the Amazon Kindle, which locks you into its own ecosystem more than I am comfortable with, so I went looking for a more open alternative. That search quickly led me to [KOReader](https://github.com/koreader/koreader), an open source document reader that runs on top of the existing firmware of many e-readers. It is easy to install on a lot of devices but particularly painless on Kobo hardware. Since I also like to read magazines I went with the [Kobo Clara Colour](https://nl.kobobooks.com/products/kobo-clara-colour).

Managing a growing e-book library can quickly get messy and that is where [Calibre](https://calibre-ebook.com) comes in. It is an open source library manager that handles conversion, organisation and metadata enrichment. KOReader ships with a [Calibre companion plugin](https://github.com/koreader/koreader/wiki/Calibre) that talks directly to a running Calibre instance over the network, which is a nice way to push new books to the device without plugging it in.

That last part only really works when the e-reader and the Calibre machine are on the same network. The obvious alternative is to port forward Calibre to the internet, but exposing it directly is not something I want to do. I run a WireGuard server at home anyway, so the natural fix was to just bring the e-reader onto that VPN whenever I needed to sync.

There is an existing [Tailscale plugin for KOReader](https://github.com/victoria-riley-barnett/koreader-tailscale) that ships with an install script and works out of the box, which is great if you are already on Tailscale. I am not, and I did not want to add another overlay network just for this, so I went looking for a WireGuard equivalent. That turned out not to exist. Digging a bit further made it clear why: there are no reputable pre-built WireGuard binaries for the Kobo and the kernel on these devices is far too old to include the in-kernel WireGuard module. The userspace implementation [wireguard-go](https://github.com/WireGuard/wireguard-go) sidesteps the kernel problem but still has to be cross-compiled for the device's architecture (`armv7l` on the Clara Colour), together with the `wg` tool from [wireguard-tools](https://github.com/WireGuard/wireguard-tools).

I cross-compiled both binaries using Docker, with a Debian armv7 container under emulation for `wg` and a regular Go toolchain targeting `armv7` for `wireguard-go`. Once they were copied onto the device the binaries themselves worked fine, so the plugin itself is really just a thin Lua wrapper around them. It adds a WireGuard entry under KOReader's Network menu with connect, disconnect, toggle and status actions, picks up any `.conf` file dropped into its `configs/` folder, and on the back of that handles the usual bring-up and tear-down steps so a single tap is enough to get the tunnel cleanly up or down.

The result is a small plugin, but it closes the last gap in my reading setup: the e-reader can now reach my Calibre library from anywhere without exposing it to the open internet.