Getting Started

This guide helps you choose between installing a ready-made release and building OperaLibre from source. Once it is running, everyday use happens in the app.

Choose the right starting point

  • You have audiobook files on this computer: download the combined release package below.
  • Your books are already in Jellyfin: you do not need to install this server. Open the OperaLibre web, macOS, or iPhone app, choose Jellyfin, enter your Jellyfin address, and sign in with your usual Jellyfin account. See Using OperaLibre.
  • You want to listen from a phone: finish the local setup first, then see Use it on a phone or tablet.

Download the combined package for your computer. It includes a background launcher and a ready-to-use configuration; no developer tools are required and no Terminal window stays open.

Follow Install a Release for exact Windows, macOS, and Linux instructions, adding books, phone access, backups, and updates.

Build from source

Use the following steps if you want to develop OperaLibre or build it yourself instead of downloading a release.

Prerequisites

Tool Version Used for
Rust stable (1.85+, edition 2024) Building and running the server
Node.js 22.12 or newer Building and serving apps/web
npm bundled with Node Workspace + dev scripts
A folder of audiobooks — The library the server will scan

Tip: If cargo --version and node --version both work, you have everything you need. On a Mac, install Apple’s Command Line Tools too by running xcode-select --install once.

1. Clone and install 

git clone https://github.com/DonovanMontoya/OperaLibre.git
cd OperaLibre
npm install

npm install installs the web workspace under apps/web. The Rust server compiles on first run.

2. Create your config 

cp server.config.example server.config

On Windows PowerShell, use this instead:

Copy-Item server.config.example server.config

Open server.config in a text editor and replace /Users/you/Audiobooks with the full path to the folder that contains your books. Keep the rest as-is for now. On Windows, use a full path such as C:\Users\you\Audiobooks.

deployment_mode = local
host =
port = 4920
max_upload_gib = 20
max_book_download_gib = 25
max_concurrent_book_downloads = 1
download_temp_dir = data/download-temp
min_download_free_gib = 2
library_root = /Users/you/Audiobooks

3. Start OperaLibre 

npm run dev

This starts the server and the web app together. Leave this Terminal window open while you listen. You should see two color-coded prefixes (server cyan, web magenta).

The Vite web app forwards its requests to the server automatically, so use the Web UI address above—not the API address—in your browser.

4. Create the admin account

Open the app for the one-time setup form. local and lan setup need no extra credential. Every setup in proxy mode asks for the 30-minute, single-use token printed in the server console. Create the initial owner account; subsequent visits show the normal sign-in form. See Users & Accounts for details.

5. Start listening

Pick a book and press play. Progress saves automatically and follows the signed-in reader across devices. See Using OperaLibre for uploading a book, adding family members, installing the web app, readalong, and the optional integrations.

Running on the LAN

To stream to a phone or tablet:

  1. Set deployment_mode = lan and leave host blank in server.config so the server selects 0.0.0.0 automatically.
  2. Find your machine’s LAN IP (ipconfig getifaddr en0 on macOS, ip addr on Linux, ipconfig on Windows).
  3. Allow port 4920 (or whatever you set) through your firewall.
  4. On the other device, open http://<your-lan-ip>:5173 in dev, sign in, and start listening. For a setup that keeps working after you close the development Terminal, use the production setup below.

Safety: LAN mode uses plain HTTP and deliberately allows a non-Secure session cookie. It is suitable only for a trusted home network or private VPN. Do not port-forward it to the public internet; use proxy mode and the HTTPS guidance in Deployment for access away from home.

npm run build

This produces:

  • A release Rust binary at apps/server/target/release/operalibre-server
  • A static web bundle at apps/web/dist/

Then add this line to server.config:

web_dist_dir = apps/web/dist

Start the server with:

./apps/server/target/release/operalibre-server

Now open http://localhost:4920. The server and web app share one address, which is simpler to bookmark and use on another device. To make it start automatically when the computer restarts, follow the macOS or Linux instructions in Deployment.

Type-checking everything 

npm run typecheck

Runs cargo check and the web app’s TypeScript compiler. Useful before committing.