BookOrbit: a self-hosted reading platform that syncs Kobo, KOReader and the web
BookOrbit: Your Reading Space
At a glance
- What is it?
- BookOrbit is an AGPL-3.0, TypeScript library server for ebooks, PDFs, audiobooks and comics. Its differentiator is three-way progress and annotation sync between a Kobo device, KOReader and its own web reader, and that is also where the operational cost sits.
- Who is it for?
- Adopt BookOrbit if you already read across a Kobo, KOReader and a browser and you are willing to run Postgres plus the app yourself; the sync and the annotation merge are the reason to pick it over a plain OPDS server. Do not adopt it if you want a single static binary or if you cannot expose an APP_URL that your devices can reach, because the sync design depends on that reachability.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- bookorbit/bookorbit6,528 ★ · +2,305
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| bookorbit/bookorbit | 4.2k | 6.5k |
2,305 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem BookOrbit picks: three reading surfaces, three sets of bookmarks
Most self-hosted library servers stop at serving files. You get an OPDS endpoint, a download, and whatever your reading app does with it. Progress then lives wherever you happened to read: the Kobo keeps its own position, KOReader keeps a sidecar file, and a browser reader keeps a third record. BookOrbit targets that split directly. The README states that progress, highlights and reading status move between the web reader, a Kobo and KOReader, and that annotations from all three merge into one searchable hub. The intended user is someone with an existing book collection and more than one device, not someone looking for a storefront. It also carries the parts a household needs: multi-user accounts with per-user permissions and isolated reading data, and OIDC login through Authentik, Keycloak or Authelia. The feature list is wide (statistics, achievements, Send-to-Kindle, outbound sync to Hardcover, Readwise and StoryGraph), which tells you the project is aiming at the whole reading workflow rather than one slice of it.
How the sync actually works, and why Postgres is not optional
The stack is TypeScript, with server/ and client/ packages, and the Docker quick start provisions three directories: books, data/app and data/postgres. That last one is the tell. Reading state is not stored as files next to your books; it lives in a database, and the sync feature is a reconciliation problem over that database. A Kobo talks to the server through its own sync protocol, KOReader talks through a plugin that the README describes as an on-device catalog browser with search, download, status and rating management, and the web reader writes to the same records. The merge is bidirectional and, per the README, includes deletions, which is the detail worth pausing on: a highlight removed on one surface is expected to disappear on the others. The KOReader plugin is the piece that does the most work here, because it is both a catalog client and a sync client. Metadata is a separate pipeline: the README overview cites 14 metadata providers, the feature list names 12 (Google Books, Open Library, Amazon, Goodreads, Kobo, Hardcover, Audible, Audnexus, Libro.fm, iTunes, ComicVine, RanobeDB), and external providers such as Douban, FantLab, J-Novel Club, Libris, LubimyCzytac and MangaBaka add more, and cover art is sourced separately from iTunes, DuckDuckGo and AudiobookCovers.
Getting it running: the four env values that decide whether it works
The README gives a four-command Docker quick start. You create a directory, make books, data/app and data/postgres, then pull .env.example and docker-compose.yml from the main branch. The README lists the values you must set in .env. APP_URL is the URL you open in the browser, BOOKS_HOST_PATH is the folder on your server holding the book files, and then POSTGRES_PASSWORD, JWT_SECRET and SETUP_BOOTSTRAP_TOKEN, with `openssl rand -hex 24` suggested for POSTGRES_PASSWORD. .env.example says SETUP_BOOTSTRAP_TOKEN is required for the initial /auth/setup endpoint (x-setup-token header). .env.example says to use an absolute BOOKS_HOST_PATH on NAS/Portainer installs, and PUID and PGID (default 1000) set the container runtime UID/GID for files written to app-managed data folders. There is a live demo with a sample public-domain library, and the README notes that some administrative features are limited there, so the demo is useful for judging the reader and the interface, not the sync configuration.
Where it will not fit: single-user readers and appliance-style deployments
The obvious limitation is the shape of the deployment. BookOrbit is a server with a database, a frontend, a setup wizard and an OIDC integration surface. If your requirement is one binary that indexes a folder and serves OPDS, this is more moving parts than you need, and the extra parts are the ones that break. The sync design also assumes reachability: your Kobo and your KOReader device have to be able to reach APP_URL, which means a hostname or address that resolves from your LAN (and from outside it if you read while travelling). The metadata layer is a second place to expect friction. Fourteen providers plus three separate cover sources means matching is a heuristic. On the maintenance side, v3.4.0, v3.5.0 and v3.6.0 shipped within roughly two weeks of each other in October 2026. That is a fast-moving project, and fast releases on a schema-backed server usually mean migrations. Plan for backups of the Postgres volume, not just the books directory.
The alternative to compare against: Calibre-Web and plain OPDS
The realistic alternative for most people evaluating BookOrbit is Calibre-Web, which serves a Calibre library over the web with OPDS and a browser reader. The difference is architectural rather than cosmetic. Calibre-Web treats the Calibre database as the source of truth and reads from it; the library is a file you manage on the host. BookOrbit owns its own Postgres database and treats the book folder as content, with reading state, annotations and user accounts living in the database. That database is the shared store BookOrbit merges highlights from three sources into. The trade is that you now have a database to back up, migrate and keep consistent with the files. If you already run Calibre and are happy with it, BookOrbit is not a drop-in replacement, it is a second system with its own copy of the state. If you run no library server at all and only want OPDS for a reading app, an OPDS-capable server is a smaller commitment than either.
Licence and upgrade cost under AGPL-3.0
BookOrbit is AGPL-3.0 per the repository metadata, and package.json gives AGPL-3.0-only. For self-hosting that is unremarkable: you run it, you keep your modifications to yourself if you are not offering it to others over a network. The clause to be aware of is the network one. AGPL-3.0 extends the source-availability obligation to users who interact with a modified version over a network, so if you fork BookOrbit, change it, and let other people log in, the licence expects those users to be offered the corresponding source. That is a description of the licence text, not legal advice; get counsel if you plan to run a modified instance for anyone outside your household. Upgrade cost is the other axis. With three releases in about two weeks and a Postgres-backed schema, the practical routine is: snapshot the database volume and the books folder, pull the new image, and be ready to read the release notes for migration steps. Keep the snapshot as your rollback.
What to verify before you migrate a real library
Start on the demo to judge the web reader, the annotation hub and the statistics screens, since the README says the demo carries a public-domain sample library and limits some admin features. Then stand up a throwaway instance with the four required env values and a small folder of test books, and check the two things the README cannot check for you. First, device sync: confirm your specific Kobo model and your KOReader version complete a round trip, because the README describes three-way sync as a capability, not as a per-model compatibility list. Second, identity: if you run Authentik, Keycloak or Authelia, complete a login before you invite other users. Only after both pass should you point BOOKS_HOST_PATH at the real collection, and when you do, keep the Postgres volume in the same backup job as the books. They are two stores, and restoring one without the other gives you files with no progress or progress with no files.
Editorial conclusion
Adopt BookOrbit if you already read across a Kobo, KOReader and a browser and you are willing to run Postgres plus the app yourself; the sync and the annotation merge are the reason to pick it over a plain OPDS server. Do not adopt it if you want a single static binary or if you cannot expose an APP_URL that your devices can reach, because the sync design depends on that reachability. Before committing, verify three things on your own hardware: that your Kobo model is handled by the sync path, that the OIDC provider you actually run (Authentik, Keycloak or Authelia) completes a login against the setup wizard, and that a restore of the Postgres volume plus the books folder brings back both files and progress, since those are two separate stores.
Frequently asked questions
What is bookorbit?
BookOrbit is a self-hosted library and reading platform for ebooks, PDFs, audiobooks, and comics, written in TypeScript and released under AGPL-3.0-only. You run it with Docker Compose and a Postgres database, then read in the built-in web reader or in the native iPhone app.
how to install bookorbit
The quick start downloads `.env.example` and `docker-compose.yml` into a fresh directory and creates `books`, `data/app`, and `data/postgres`. Set `APP_URL`, `BOOKS_HOST_PATH`, `POSTGRES_PASSWORD`, `JWT_SECRET`, and `SETUP_BOOTSTRAP_TOKEN`, then run `docker compose up -d` and finish setup in the browser with the bootstrap token.
how to use book orbit
You read in the built-in web reader or in the iPhone app, and both connect to the server you host. Progress and highlights travel between Kobo devices, KOReader, and the web reader, metadata is filled in from fourteen providers, and OPDS plus a Book Dock drop folder handle delivery and importing.
What is the best app for cataloging your books?
For cataloging, BookOrbit separates content into multiple libraries with per-library folders, custom scan rules, and format priorities, adds rule-based saved filters and curated collections, and pulls records from sources such as Open Library, Amazon, Goodreads, Kobo, Audible, and ComicVine. Cover art is fetched separately from iTunes, DuckDuckGo, and AudiobookCovers.
What is the best library app for free books?
The public demo at `demo.bookorbit.app` opens without an account and carries a sample library of public domain books, though some administrative features are limited there. BookOrbit itself carries an AGPL-3.0-only license and runs on hardware you control, and the project publishes native iPhone and Apple Watch apps for it.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/bookorbit-bookorbit)Star history chart for your README
[](https://hysenlabs.com/projects/bookorbit-bookorbit)Was this useful?