From Wallabag to Joplin: Closing the Reading Loop with KOReader
How a read-it-later pipeline becomes a personal knowledge workflow with Joplin Server, Joplin Desktop, Joplin Android, the Web Clipper API, and KOReader.
The Previous Step
The Wallabag setup gives us the first half of the reading system: a self-hosted place to save articles before reading them.
That is useful by itself, especially when combined with KOReader. Wallabag keeps the incoming queue, KOReader gives a focused reading experience, and the device becomes less dependent on browser tabs, newsletters, and transient links.
The missing part is what happens after reading.
Some articles are disposable. Others produce notes, highlights, excerpts, summaries, or follow-up ideas. That material should not stay trapped inside a reader device. It should land in a durable note system that syncs across machines.
That is where Joplin fits.
before reading during reading after reading
+----------------+ +----------------+ +----------------+
| | | | | |
| Wallabag | -----------> | KOReader | -----------> | Joplin |
| | | | | |
+----------------+ +----------------+ +----------------+
saved articles focused reading notes/highlights
Wallabag remains the read-it-later service. Joplin becomes the long-term note store.
Why Add Joplin?
Joplin is an open source note-taking application with end-to-end encryption support, Markdown notes, notebooks, tags, attachments, and clients for desktop and mobile.
Running Joplin with a private server gives a few practical advantages.
One Note Graph Across Devices
The desktop app, Android app, and other clients can all sync against the same server. A note exported from KOReader on one device becomes available later on the laptop or phone.
+----------------+
| |
| Joplin Server |
| |
+-------+--------+
^
|
sync | sync
|
+----------------+ | +----------------+
| | | | |
| Joplin Desktop | ------+------ | Joplin Android |
| | | |
+----------------+ +----------------+
The server is the synchronization target. The apps are where reading, editing, searching, and organizing happen.
Ownership Without Giving Up Convenience
The data lives on infrastructure you control, but the user experience is still that of a normal notes app. Desktop and mobile clients continue to work offline and sync when connectivity is available.
A Better Destination for Reading Notes
KOReader is excellent for reading, but it is not where I want a permanent knowledge base to live. Joplin is a better place for long-lived notes because it provides notebooks, search, tags, attachments, sync, and editing from multiple clients.
Complementary to Wallabag
Wallabag and Joplin do not replace each other.
+----------------+ +----------------+ +----------------+
| | | | | |
| Wallabag | ----> | KOReader | ----> | Joplin |
| | | | | |
+----------------+ +----------------+ +----------------+
queue of things reading surface permanent notes
to read later and annotations and highlights
Wallabag answers: what do I want to read?
Joplin answers: what do I want to keep from what I read?
The Important Joplin Components
The naming can be confusing because there are several Joplin pieces, and they do not all serve the same API.
Joplin Server
Joplin Server is the sync backend. It stores note data for synchronization between clients.
In this example, the public sync endpoint is:
https://joplin.example.com
This is the URL that Joplin Desktop and Joplin Android use for sync.
Joplin Desktop
Joplin Desktop is the full desktop note application. It syncs with Joplin Server, but it also exposes a separate local API called the Web Clipper service.
That Web Clipper service usually listens on:
http://127.0.0.1:41184
This is the API used by browser clippers and integrations such as the KOReader Joplin plugin.
Joplin Android
Joplin Android is the mobile note client. It syncs with Joplin Server and gives access to the same notebooks and notes from the phone.
It is not the Web Clipper API endpoint for KOReader.
Web Clipper Service
The Web Clipper service is provided by Joplin Desktop, not by Joplin Server.
This distinction matters. If this URL:
https://joplin.example.com/ping
returns something like:
Path not found: ping
then the request is reaching Joplin Server, not the Joplin Desktop Web Clipper service.
For the Web Clipper API, the expected response is:
JoplinClipperServer
The relationship looks like this:
sync API
+------------------------------------+
| |
v v
+----------------+ +----------------+
| | | |
| Joplin Desktop | | Joplin Android |
| | | |
+-------+--------+ +-------+--------+
^ ^
| |
| sync |
+---------------+-------------------+
|
v
+---------------+
| |
| Joplin Server |
| |
+---------------+
local integration API
+----------------+ http://127.0.0.1:41184
| | <--------------------------------+
| Joplin Desktop | |
| Web Clipper | |
+----------------+ |
|
+------v-------+
| |
| KOReader |
| |
+--------------+
There are two APIs in play:
- Joplin Server sync API: used by Joplin clients.
- Joplin Desktop Web Clipper API: used by KOReader export.
Running Joplin Server
Joplin Server should be treated as the always-on synchronization point for the note system. It does not replace the desktop or mobile apps. Instead, it gives them a common place to exchange note changes.
The server needs a stable address that the clients can reach. In this setup that address is https://joplin.example.com. The exact hosting method is not important for the reading workflow. It can be a small server, a NAS, a VPS, or another machine that stays available.
Conceptually, the server sits behind a public or private URL and stores its data in a database. The Joplin clients do not need to know the database details. They only need the server URL and the account credentials.
+-------------------+ +---------------+ +----------------+
| | | | | |
| joplin.example.com | ---> | Reverse Proxy | ----> | Joplin Server |
| | | | | |
+-------------------+ +---------------+ +-------+--------+
|
v
+---------------+
| |
| PostgreSQL |
| |
+---------------+
After the server is available, create the Joplin user account that will be used by the desktop and Android clients. That account is what ties the devices together.
That public URL is for synchronization. It is not the Web Clipper URL, and it is not the endpoint KOReader exports to.
Setting Up Joplin Desktop
Install Joplin Desktop on the workstation where notes will be edited most often.
Then configure sync:
- Open Joplin Desktop.
- Go to
Tools->OptionsorPreferences. - Open
Synchronisation. - Select
Joplin Serveras the sync target. - Set the server URL to
https://joplin.example.com. - Enter the Joplin Server username and password.
- Press
Check synchronisation configuration. - Run the first sync.
The desktop app now participates in the server-backed note graph:
+----------------+ sync +----------------+
| | ---------------------------> | |
| Joplin Desktop | | Joplin Server |
| | <--------------------------- | |
+----------------+ sync +----------------+
Next enable the Web Clipper service:
- Open
Tools->OptionsorPreferences. - Open
Web Clipper. - Enable the Web Clipper service.
- Copy the authorization token.
Joplin Desktop should now answer locally:
http://127.0.0.1:41184/ping
with:
JoplinClipperServer
This token is the token that KOReader needs.
Setting Up Joplin Android
Install Joplin on Android and configure it against the same server.
- Open Joplin Android.
- Go to
Configuration. - Open
Synchronisation. - Select
Joplin Server. - Set the server URL to
https://joplin.example.com. - Enter the same Joplin Server credentials.
- Run sync.
After the first sync, notes created on desktop should appear on Android, and notes edited on Android should sync back to the server.
+----------------+ +----------------+ +----------------+
| | sync | | sync | |
| Joplin Desktop | <--------> | Joplin Server | <--------> | Joplin Android |
| | | | | |
+----------------+ +----------------+ +----------------+
At this point Joplin sync is working, but KOReader export still needs access to the Web Clipper API.
Exposing the Web Clipper Service
The Web Clipper service is local to Joplin Desktop. By default it often binds only to localhost:
127.0.0.1:41184
That works for browser extensions running on the same computer, but it does not work for KOReader running on an e-reader or phone.
From the KOReader device, this is wrong:
http://127.0.0.1:41184
On the KOReader device, 127.0.0.1 means the KOReader device itself, not the laptop running Joplin Desktop.
The desired path is:
+----------------+ LAN HTTP +----------------+
| | ----------------------> | |
| KOReader | | Joplin Desktop |
| | <---------------------- | Web Clipper |
+----------------+ +----------------+
http://192.168.1.x:41184 127.0.0.1:41184 or LAN bind
Option 1: Enable External Connections in Joplin
Some Joplin Desktop versions expose a Web Clipper setting that allows connections from other machines.
If available:
- Open
Web Clippersettings in Joplin Desktop. - Enable the option that allows external or non-localhost connections.
- Restart the Web Clipper service or restart Joplin.
- Find the workstation LAN IP.
- Test from another device:
http://192.168.1.x:41184/ping
Expected response:
JoplinClipperServer
If that works, use this as the KOReader Joplin server URL:
http://192.168.1.x:41184
Option 2: Forward a LAN Port with socat
If Joplin Desktop only binds to localhost, expose a separate LAN listener that forwards traffic to the local Web Clipper service.
On the workstation running Joplin Desktop:
socat TCP-LISTEN:41185,fork,bind=0.0.0.0 TCP:127.0.0.1:41184
This creates a listener on all network interfaces at port 41185 and forwards requests to the local Joplin Web Clipper service.
KOReader device desktop machine
+-------------+ LAN +----------------+ localhost +----------------+
| | ------------> | socat :41185 | -----------------> | Joplin Clipper |
| KOReader | | 0.0.0.0 | | 127.0.0.1:41184|
| | <------------ | | <----------------- | |
+-------------+ +----------------+ +----------------+
http://192.168.1.x:41185
Then test from another device:
http://192.168.1.x:41185/ping
Expected response:
JoplinClipperServer
If a firewall is enabled on the desktop machine, allow inbound traffic to the chosen port.
Only expose this on a trusted LAN. The Web Clipper API is protected by a token, but it is still a write-capable note API.
Option 3: SSH Tunnel
If the KOReader device can reach an SSH-capable machine, another option is to tunnel the port instead of binding it broadly to the LAN.
The exact tunnel shape depends on where Joplin Desktop runs, but the idea is the same: make 127.0.0.1:41184 on the desktop available at an address the reader device can reach.
For a simple home LAN, socat is usually easier.
When Local Network Access Is Not Available
The simplest setup assumes KOReader and Joplin Desktop are on the same trusted network. That is not always true. The reader may be on a guest network, a mobile hotspot, a university network, a hotel Wi-Fi, or outside the house entirely.
The core requirement does not change: KOReader must be able to reach the Joplin Desktop Web Clipper API somehow. The question is how to create a safe path between the reader and the machine running Joplin Desktop.
Use a VPN
A VPN is usually the cleanest workaround. Put the KOReader device and the Joplin Desktop machine on the same private overlay network, then configure KOReader with the VPN address of the desktop machine.
This keeps the Web Clipper service away from the public internet while still making it reachable from outside the local LAN.
outside LAN private VPN network
+-------------+ VPN +----------------+ localhost +----------------+
| | --------------> | Desktop VPN IP | -------------------> | Joplin Clipper |
| KOReader | | | | 127.0.0.1:41184|
| | <-------------- | | <------------------- | |
+-------------+ +----------------+ +----------------+
This can be done with tools such as WireGuard, Tailscale, ZeroTier, NetBird, or another VPN already used on the network. The operational detail is different for each tool, but the model is the same: KOReader reaches the desktop through a private address instead of a LAN address.
Use this when:
- the reader is often outside the home network,
- you do not want to expose Web Clipper publicly,
- and the KOReader device can run or route through the VPN.
Use a Travel Router
Some e-readers are awkward VPN clients. In that case, a small travel router can join the VPN and provide a local Wi-Fi network for the reader.
KOReader does not need to know about the VPN. It only connects to the travel router Wi-Fi. The router handles the private route back to the desktop machine.
+-------------+ Wi-Fi +---------------+ VPN +----------------+
| | ------------------> | Travel Router | ---------------> | Joplin Desktop |
| KOReader | | VPN client | | Web Clipper |
| | <------------------ | | <--------------- | |
+-------------+ +---------------+ +----------------+
This is useful when the reader device has limited networking features but can still connect to normal Wi-Fi.
Use an SSH Tunnel Through a Trusted Host
An SSH tunnel can also bridge the gap if there is a trusted machine that both sides can reach. Conceptually, the tunnel takes the local-only Web Clipper service on the desktop and makes it available somewhere else in a controlled way.
This is more manual than a VPN, but it can be useful for testing or temporary access.
Use this when:
- you already have SSH access to a trusted host,
- the setup is temporary,
- and you do not want to permanently expose another network listener.
Export Later
The lowest-tech workaround is to accept that Joplin export is not always available. KOReader can still be used for reading while offline or away from the right network. When the device is back on a network that can reach the Web Clipper service, export the notes then.
This is often good enough. Reading and annotation do not require Joplin to be reachable at all times. Only the export step does.
away from home later, on reachable network
+-------------+ +-------------+ export +----------------+
| | | | -----------------> | Joplin Desktop |
| KOReader | annotations | KOReader | | Web Clipper |
| | kept locally | | <----------------- | |
+-------------+ +-------------+ +----------------+
Avoid Public Web Clipper Exposure
It may be tempting to publish the Web Clipper API directly on a public domain. That should be avoided unless there is a very specific reason and additional access controls are in place.
The Web Clipper API can create and modify notes. The token is important, but it should not be treated as the only security boundary for a public internet service. Prefer VPN access, a trusted tunnel, or delayed export.
Integrating KOReader with Joplin
Once the Web Clipper API is reachable, configure KOReader.
- Open KOReader.
- Open the Joplin plugin settings.
- Set the server URL to the Web Clipper endpoint, not the Joplin Server endpoint.
- Paste the Web Clipper authorization token from Joplin Desktop.
- Export a test note or highlight.
If Joplin Desktop is reachable directly on the LAN, the URL is usually:
http://192.168.1.x:41184
If using socat, use the forwarded port:
http://192.168.1.x:41185
Do not use this for KOReader export:
https://joplin.example.com
That is the Joplin Server sync endpoint, not the Web Clipper endpoint.
The final flow looks like this:
article queue reading export API
+----------+ +-------------+ +----------------+
| | | | | |
| Wallabag | -----------> | KOReader | -----------> | Joplin Desktop |
| | | | | Web Clipper |
+----------+ +-------------+ +-------+--------+
|
| sync
v
+---------------+
| |
| Joplin Server |
| |
+-------+-------+
|
| sync
v
+---------------+
| |
| Joplin Android|
| |
+---------------+
There are two different network relationships:
- KOReader exports to Joplin Desktop Web Clipper.
- Joplin Desktop syncs the resulting note to Joplin Server.
That separation is the most important operational detail in the whole setup.
Troubleshooting
Path not found: ping
This usually means the request is going to Joplin Server instead of the Web Clipper service.
For example:
https://joplin.example.com/ping
returning:
Path not found: ping
means joplin.example.com is serving the sync backend, not the Web Clipper API.
Use the desktop Web Clipper address instead:
http://192.168.1.x:41184/ping
or the forwarded address:
http://192.168.1.x:41185/ping
Joplin: Failed to export
Check the basics in this order:
- Joplin Desktop is running.
- The Web Clipper service is enabled.
/pingreturnsJoplinClipperServerfrom the KOReader device.- KOReader is using the Web Clipper URL, not the Joplin Server URL.
- The Web Clipper authorization token is correct.
- The desktop firewall allows inbound traffic to the clipper or forwarded port.
127.0.0.1 Works on Desktop but Not on KOReader
That is expected. 127.0.0.1 always means the current device.
From KOReader, use the LAN IP of the workstation running Joplin Desktop:
http://192.168.1.x:41184
or the forwarded port:
http://192.168.1.x:41185
The Result
Wallabag and Joplin form complementary halves of the reading workflow.
Wallabag owns the incoming queue. KOReader owns the focused reading session. Joplin owns the long-term notes.
save read keep
+------------+ +-----------+ +-------------+
| | | | | |
| Wallabag | ----> | KOReader | ----> | Joplin |
| | | | | |
+------------+ +-----------+ +-------------+
Joplin Server makes the notes available everywhere. Joplin Desktop provides both the editing environment and the Web Clipper API that KOReader can export into. Joplin Android gives mobile access to the same material.
The only non-obvious part is that KOReader does not export directly to Joplin Server. It exports to the Joplin Desktop Web Clipper service, and then Joplin Desktop syncs the resulting note through Joplin Server.
Once that distinction is clear, the system becomes simple: one queue, one reader, one note graph, and all of it running on infrastructure we control.
This article continues the Wallabag reading workflow by adding Joplin as the durable destination for notes, highlights, and follow-up ideas.