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:

  1. Open Joplin Desktop.
  2. Go to Tools -> Options or Preferences.
  3. Open Synchronisation.
  4. Select Joplin Server as the sync target.
  5. Set the server URL to https://joplin.example.com.
  6. Enter the Joplin Server username and password.
  7. Press Check synchronisation configuration.
  8. 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:

  1. Open Tools -> Options or Preferences.
  2. Open Web Clipper.
  3. Enable the Web Clipper service.
  4. 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.

  1. Open Joplin Android.
  2. Go to Configuration.
  3. Open Synchronisation.
  4. Select Joplin Server.
  5. Set the server URL to https://joplin.example.com.
  6. Enter the same Joplin Server credentials.
  7. 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:

  1. Open Web Clipper settings in Joplin Desktop.
  2. Enable the option that allows external or non-localhost connections.
  3. Restart the Web Clipper service or restart Joplin.
  4. Find the workstation LAN IP.
  5. 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.

  1. Open KOReader.
  2. Open the Joplin plugin settings.
  3. Set the server URL to the Web Clipper endpoint, not the Joplin Server endpoint.
  4. Paste the Web Clipper authorization token from Joplin Desktop.
  5. 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:

  1. Joplin Desktop is running.
  2. The Web Clipper service is enabled.
  3. /ping returns JoplinClipperServer from the KOReader device.
  4. KOReader is using the Web Clipper URL, not the Joplin Server URL.
  5. The Web Clipper authorization token is correct.
  6. 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.