The quick answer
An OPDS server publishes your ebook library as a catalog that e-reader apps can browse and download from. OPDS stands for Open Publication Distribution System. It is an open standard built on Atom and HTTP, and it is how KOReader, Thorium and Librera see a library that lives on another machine.
You need three things: a catalog URL, a server the device can reach, and a reader that speaks OPDS. The setup is usually four steps:
- Put your books in a library that exposes OPDS.
- Copy the catalog URL, including any token or credentials.
- Paste it into the reader’s OPDS or catalog screen.
- Browse the feed and download a book.
If you want the short version for Librost: open OPDS in the sidebar, choose New Token, name it after the device, copy the URL shown next to the token, and paste it into your reader. The rest of this guide covers what sits behind that URL and how to run the other common servers.
What is an OPDS server?
OPDS is a syndication format for electronic publications. The current XML specification, OPDS 1.2, was published on 11 November 2018 and is built on Atom and HTTP. OPDS 2.0 is the newer JSON format, based on the Readium Web Publication Manifest, and its core has been stable since 2017.
An OPDS server is the software that publishes the feeds. A catalog is made of two kinds of feed:
- Navigation feeds create a browsable hierarchy. Their entries link to other feeds, not to books. A root feed might offer “All books”, “Recently added” and “Authors”.
- Acquisition feeds list publications. Each entry carries metadata (title, author, language, cover) and at least one acquisition link pointing to a file the client can download.
A minimal OPDS 1.2 entry looks like this:
<entry>
<title>Moby-Dick</title>
<id>urn:uuid:6f6a2b1e-8f3c-4a57-9d21-3c0e5b7a91d4</id>
<updated>2026-11-09T10:00:00Z</updated>
<author><name>Herman Melville</name></author>
<link rel="http://opds-spec.org/image" href="/covers/moby-dick.jpg" type="image/jpeg"/>
<link rel="http://opds-spec.org/acquisition" href="/files/moby-dick.epub" type="application/epub+zip"/>
</entry>
The client reads that entry, shows the cover and title, and downloads the EPUB when the reader taps it. OPDS describes the books and links to the files. Stores, DRM and reading interfaces are somebody else’s job.
The media types matter when something breaks. OPDS 1.2 feeds use application/atom+xml;profile=opds-catalog;kind=navigation or kind=acquisition; entries use application/atom+xml;type=entry;profile=opds-catalog. OPDS 2.0 uses application/opds+json. A client that only understands one format will show nothing for the other.
How an OPDS request works
The exchange is ordinary HTTP:
- The reader requests the catalog root.
- The server returns a navigation feed or an acquisition feed.
- The reader follows a
subsectionorstartlink to a list of books. - The reader requests an acquisition link and receives the book file.
Along the way, servers can advertise search, pagination, facets and cover images:
- Search uses an OpenSearch description document linked with
rel="search"and the typeapplication/opensearchdescription+xml. The template contains a{searchTerms}placeholder. - Pagination uses
first,prev,nextandlastlinks, following RFC 5005. - Facets are links with the relation
http://opds-spec.org/facet, used to filter or reorder a feed. - Covers use
http://opds-spec.org/imageandhttp://opds-spec.org/image/thumbnail.
This is why the same catalog can look like a grid of covers in one app and a plain list in another. The server describes the library; the client decides how to present it.
What the URL actually contains
Most servers expose a root such as:
https://books.example.com/opds
Librost uses a token in the path, so the URL itself carries the credential:
https://api.example.com/opds/AbCdEfGhIjKlMnOpQrStUvWx
The token is the part after /opds/. In Librost it is 24 characters, can be created per device, and can be revoked without changing anything else. The same token can also be sent as the username or password in HTTP Basic authentication, which is the fallback when an app asks for a “server address, username and password” instead of a single URL.
Treat the full URL as a password, because anyone holding it can browse and download while the token is valid. Use HTTPS too: Basic authentication encodes the credential, it does not encrypt it.
What you need to run one
| Piece | What it does | Practical choice |
|---|---|---|
| A library | Holds the book files and metadata | Calibre library, a folder of EPUBs, or a hosted library |
| An OPDS server | Publishes the catalog and serves downloads | Librost, Calibre content server, Calibre-Web, COPS, Komga, Kavita |
| A network path | Lets the reader reach the server | Public HTTPS, a VPN or Tailscale, or the same home network |
| An OPDS client | Browses the catalog and downloads books | KOReader, Thorium, Librera, Moon+ Reader, FBReader |
The first two are the part people call “setting up an OPDS server”. The third is where most failures happen.
How to set up an OPDS server
Option 1: a hosted catalog (no server to run)
This is the shortest path, and the one Librost is built for. You do not install anything, open a port or maintain a container.
- Add your EPUBs, PDFs and audiobooks to the library. Librost keeps several files under one book entry, so an EPUB and a PDF of the same title stay together.
- Open OPDS in the sidebar and choose New Token. Give it the name of the device, for example “Kobo Libra” or “Phone”.
- Copy the OPDS URL shown next to that token. It looks like
https://.../opds/<token>. - Paste the URL into the reader’s OPDS screen. If the app asks for a server, username and password instead, use the server URL without the token and paste the token as the password.
The catalog lists your books with covers and metadata, and downloads the format the reader asks for. Librost serves EPUB, PDF, MOBI, AZW3, CBZ and CBR files, so a comics reader and an e-reader can use the same library. The catalog is paginated at 20 books per page by default.
Because the token is part of the URL, a reader that cannot handle a login prompt still works. Revoking the token in the app cuts that device off immediately.
Option 2: the Calibre content server
Calibre is the reference implementation for most people: free, already on your computer, and able to publish OPDS on its own.
- In Calibre, choose Connect/share → Start content server.
- Note the address Calibre shows, usually
http://192.168.1.x:8080on the local network. - Turn on authentication in Preferences → Sharing over the net before you expose it beyond your home network.
- In the reader, use the server address plus
/opds, for examplehttp://192.168.1.5:8080/opds.
Calibre’s server supports both OPDS 1 and OPDS 2 catalogs, and its documentation notes that applications can request the JSON catalog with Accept: application/opds+json. It also offers full-text search inside books when a library has been indexed.
The catch is reachability. On your home network, the local IP is enough. Away from home you need port forwarding, a reverse proxy with HTTPS, or a VPN such as Tailscale or WireGuard. Calibre’s own documentation warns that the local address only works on the machine running the server, and that exposing the server without a password lets anyone read your library.
Option 3: Calibre-Web, COPS, Komga or Kavita
These are self-hosted front ends that sit on top of a library. They are the usual choice for people who want a web interface, multiple users or comics.
- Calibre-Web runs in Docker, reads an existing Calibre library and publishes OPDS at
/opds. It adds shelves, users and a browser reader. - COPS (Calibre OPDS PHP Server) is a lightweight PHP application that serves a Calibre library over OPDS. It is often installed alongside a web server or in a small container.
- Komga is aimed at comics and manga, with ebook support. It documents versioned OPDS endpoints; use the URL shown in its own documentation rather than guessing.
- Kavita is a reading server with OPDS and KOReader progress sync. Its catalog URL includes an API key generated in the dashboard.
All four need the same work: a service that stays running, a reverse proxy if you want HTTPS and a stable hostname, and backups.
| Option | Cost | Remote access | Auth | Best for |
|---|---|---|---|---|
| Librost | Free for 5 books, then 39 USD one-time | Built in over HTTPS | Per-device token or Basic | A library you own without running a server |
| Calibre content server | Free | Local network by default; proxy or VPN for remote | Username and password | One desktop that is already your Calibre library |
| Calibre-Web | Free, self-hosted | Reverse proxy or VPN | Web login, OPDS auth | A browser interface and multiple users |
| COPS | Free, self-hosted | Web host or container | Web server auth | A small PHP-only deployment |
| Komga | Free, self-hosted | Reverse proxy or VPN | User accounts | Comics and manga |
| Kavita | Free, self-hosted | Reverse proxy or VPN | API key in the URL | Reading servers with KOReader sync |
How to connect common OPDS readers
KOReader (Kindle, Kobo, PocketBook, Android)
KOReader is the most common OPDS client on E Ink. It ships with public catalogs such as Project Gutenberg and Standard Ebooks, and adding your own takes one screen.
- Open KOReader’s file browser.
- Open the top menu and choose Search → OPDS catalog.
- Add a catalog: give it a name and paste the URL, including the token if the server uses one.
- Open the catalog, browse to a book and download it. The file lands in the folder KOReader uses for downloads.
KOReader handles OPDS 1.x feeds and is the usual way to put OPDS on a Kobo or a jailbroken Kindle. It can also sync reading progress, but that uses its own sync service, not OPDS.
Thorium Reader (Windows, macOS, Linux)
Thorium is the desktop reference reader from EDRLab. It has a Catalogs panel: add a catalog, paste the URL, and the feed appears as a browsable list. Thorium supports OPDS 1 and 2, which makes it a useful test client when you are unsure which format a server publishes.
Android and iOS readers
The exact labels vary, but the shape is the same: look for OPDS, Catalogs, Net library or Online catalogs in the app’s library or file screen, add a catalog, and paste the URL.
- Librera Reader (Android) has a dedicated OPDS Catalogs section and supports adding custom catalogs.
- Moon+ Reader (Android) exposes OPDS under its Net library.
- FBReader (Android, iOS, macOS) has an OPDS catalogs screen.
- PocketBook Reader (Android, iOS) supports OPDS catalogs.
- Yomu and Panels (iOS) support OPDS; Panels is aimed at comics.
- Calibre itself can act as a client through Get books, which is useful for testing a feed on a desktop.
A reader that only implements OPDS 1.2 will not open an OPDS 2.0 endpoint, and vice versa. If a catalog is silent, try the other endpoint before assuming the server is broken.
Authentication, tokens and why e-readers struggle
E Ink devices are the reason OPDS servers keep a token-in-URL option. Many readers handle HTTP Basic authentication badly, and some cannot show a login prompt at all. A URL with the credential embedded avoids that problem, but it moves the secret into a place that is easy to leak.
Set it up this way:
- One token per device. If a phone is lost, revoke that token and leave the e-reader alone.
- HTTPS only. A token in a URL over plain HTTP is readable by anyone on the network.
- No shared screenshots. The URL is the password.
- No open catalogs. A public OPDS feed with no authentication is fine for a public-domain library and a bad idea for your purchases.
- Replace leaked tokens. A token posted in a support thread should be replaced.
Librost accepts the token either in the path or as the Basic username or password, so the same credential works whether the app asks for one field or three. Tokens are created and revoked from the OPDS screen.
Common OPDS problems and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 Unauthorized | Token or password is wrong, missing or revoked | Recopy the full URL; create a fresh token; if the app asks for a login, paste the token as the password |
| Connection times out | Wrong host or port, server off, firewall blocking | Open the URL in a browser on the same network; check the server is running; allow the port |
| Certificate error | Self-signed certificate or a hostname mismatch | Use a valid certificate, or import the CA on the device; do not disable checks permanently |
| Catalog opens but is empty | Wrong account, empty library, or a filter | Confirm the books are in that account; remove search or facet filters; refresh the catalog |
| Covers are missing | Image URLs are unreachable or the client rejects the image type | Check the cover URL in a browser; use JPEG or PNG; refresh the feed |
| Download fails | Client filters the file type, or auth fails on the redirect | Try a different format (EPUB rather than MOBI); confirm the acquisition link opens in a browser |
| No search box | Server does not advertise an OpenSearch description | Search in the library app instead; only some servers expose search to clients |
| Works at home, not away | The URL is a local IP address | Use a public HTTPS hostname, a reverse proxy, or a VPN such as Tailscale |
| OPDS 2.0 client shows nothing | The server only publishes Atom feeds | Use the OPDS 1.2 endpoint, or a client that supports the server’s format |
Some readers keep a stale catalog listing after the server changes. Pull to refresh, or remove and re-add the catalog. If a book was replaced, an old entry can point at a file that no longer exists.
What OPDS does not do
OPDS carries the catalog and the files. Everything else belongs to other software:
- Reading position stays with the reader. Progress sync is a separate protocol: KOReader has its own sync service, and Calibre exposes
/kosyncfor KOReader. - Highlights and annotations stay in the reader as well.
- Format conversion is not part of it. If the server offers EPUB and the client only reads MOBI, the catalog entry may be hidden or the download may fail. Convert the file first.
- Library management happens in the server’s own interface, not through OPDS.
- Calibre manages the library and publishes the feed from it. The feed is the delivery layer.
Self-hosted or hosted?
Self-hosting makes sense when you already run a home server, you want full control of the files, or you need a web interface for several people. The cost is maintenance: updates, backups, a reverse proxy, certificates and a way to reach the server when you are away from home.
A hosted catalog makes sense when you want the library to be reachable from any device without opening a port, and when you would rather pay once than run a container. That is the trade Librost sells: your files, an OPDS URL per device, and no server to patch.
Either way, set it up in the reader you use every day first and leave the rest for later.
Your library is already an OPDS server
Librost keeps your EPUBs, PDFs and audiobooks in one searchable library and gives each device its own OPDS URL. Add a token, paste it into KOReader or Thorium, and your books appear there on the next refresh. Free for your first 5 books; the lifetime licence is 39 USD once, with 3 GB of storage.
Start your free library →Keep reading
- ePub to Kindle: every method that works in 2026 for the cases where the book has to reach an Amazon device.
- The free ePub Metadata Editor to fix the title, author and language that show up in an OPDS feed.
- The free ePub Cover Changer when the catalog shows an old or missing cover.