Armarium. GitHub

Self-hosted. Open source. Yours.

Your collection.
A lighter home.

A small Go server for your books and comics. Point it at a folder or a Calibre library. Browse, read, and serve your collection over OPDS.

Set up your library Explore the source

One binary. Your existing files. A little more room to read.

Armariumyour library / your server

Your library

A shelf worth coming back to.

Continue readingThe Odyssey
38%
A familiar shelf, a smaller footprint.Illustrative preview
Small by designGo + SQLite
Easy to runOne static binary
Reader friendlyOPDS 1.2 + JSON API
Gentle on your libraryRead-only source files

01 / The idea

A cupboard
for your books.

armarium / noun
The cupboard where a medieval monastery kept its books.

I wanted a simple way to serve my collection.

Kavita and Calibre-Web felt resource-heavy for what I needed: a lightweight OPDS server for my own books and comics. So I made Armarium in Go.

It keeps the job small. Read the files I already have, make them easy to browse, and get them to the reader I want to use. A single binary, an embedded web UI, and SQLite, with incremental scans that only open new or changed files.

Keep managing metadata in Calibre if you like. Armarium reads its library directly, including titles, authors, series, tags, covers, and available formats.

02 / What it does

Everything on your shelf.

Books, comics, and the tools
to get back to them.

Your folders. Your Calibre.

Add ordinary book and comic folders, or point at a Calibre library’s metadata.db. Source libraries stay read-only; Armarium writes to its own data folder.

Read right in the browser.

A cover grid, search, and filters, with an EPUB reader, a comic viewer, and PDFs opened in the browser. Works on a desktop or a phone.

A catalogue for your readers.

OPDS 1.2 with search, recent additions, and continue reading. Stream CBZ and CBR pages with OPDS-PSE, or download the whole file.

Keep your place.

Server-side progress is shared by the web UI, OPDS page streaming, and readers using the Armarium API. Import existing progress from Kavita.

Connect a phone in a scan.

Pair Skrivist Books or Comics with an Admin QR code. Each device gets its own revocable token. The web UI uses an owner login.

Small enough to stay simple.

Pure-Go SQLite, an embedded UI, and no background scanning by default. Run in Docker on your NAS, or use the binary with a small JSON API for your own tools.

On the shelfEPUBPDFCBZCBR

Other Calibre formats, including MOBI and AZW3, are available as downloads.

Built for a personal collection. Metadata editing, scraping, and multiple user accounts are outside Armarium’s scope.

03 / Basic usage

Make yourself at home.

Full deployment guide

A server.
A folder.
A shelf.

Armarium needs a configuration file, a writable data folder, and read access to your collection.

Docker images are available for Linux amd64 and arm64. The deployment guide also covers Synology and systemd.

See all settings

After starting, log in and run a scan from Admin. Your covers and collection will appear in the library.

  1. Get the starter files.

    Terminal
    mkdir -p armarium/data && cd armarium
curl -LO https://raw.githubusercontent.com/c0ze/armarium/main/deploy/compose.yaml
curl -L -o armarium.toml https://raw.githubusercontent.com/c0ze/armarium/main/deploy/armarium.example.toml

  2. Point it at your collection.

    Edit compose.yaml: replace the library mount paths with your own and keep :ro. Set user: to the owner of ./data (check with id -u and id -g).

    In armarium.toml, use listen = "0.0.0.0:8580", add the host names or IP addresses you’ll use to allowed_hosts, and set each library’s path as seen inside the container.

  3. Set a password. Start the server.

    Generate your password hash
    docker run --rm -i ghcr.io/c0ze/armarium hash-password

    Enter a password of at least eight characters. Paste the printed hash into password_hash in your config, then start Armarium:

    Start
    docker compose up -d

    Open http://localhost:8580 on the server, or http://<your-host>:8580 from another device. Log in and scan from Admin.

  1. Download the binary for your platform.

    Get and unpack the matching archive from GitHub Releases. The web UI is already inside the binary.

    Get a configuration file
    curl -L -o armarium.toml https://raw.githubusercontent.com/c0ze/armarium/main/deploy/armarium.example.toml
./armarium hash-password

    On Windows, run .\armarium.exe in place of ./armarium.

  2. Edit your configuration.

    Paste the printed hash into password_hash. Set data_dir to a writable folder and change the [[library]] roots to your collection’s actual paths. Use calibre = true for a Calibre library.

    The default address, 127.0.0.1:8580, is for this computer. To serve other devices, set listen = "0.0.0.0:8580" and add the host names or IP addresses to allowed_hosts.

  3. Open your library.

    Start
    ./armarium serve

    Open http://127.0.0.1:8580, log in, and run a scan from Admin. For an always-on Linux setup, follow the systemd instructions.

Prefer to build it? Source instructions use Go 1.25+, Node 22+, and make.

04 / The companion apps

Your server. Your next read.

Armarium keeps the collection.
Skrivist brings it to your screen.

For the dog-eared pages

Skrivist Books

A quiet EPUB and PDF reader in your browser. Adjust the type and paper, navigate chapters, and save notes. Open books from Armarium’s OPDS catalogue and keep downloaded books on your device for offline reading.

EPUB + PDFOffline readingNotes + exports
Open Skrivist Books
For the next panel

Skrivist Comics

A CBZ, CBR, and PDF reader with guided panel-by-panel reading. Panel detection runs in your browser. Browse your Armarium catalogue, choose an issue, and download it for reading, including offline.

CBZ + CBR + PDFGuided viewLocal detection
Open Skrivist Comics

Better together

From shelf to phone.
With one QR code.

The hosted Skrivist apps connect directly to Armarium from your browser. Give your server an HTTPS address the phone can reach, then allow both readers in your config.

Your filesArmariumSkrivist

Books and issues downloaded through OPDS keep their reading positions in that browser. Server progress sync is available through Armarium’s web UI, OPDS page streaming, and the Comics reader’s Armarium mode.

armarium.toml · replace the example host
allowed_hosts = ["armarium.example.com"]
public_url = "https://armarium.example.com"
cors_origins = [
  "https://books.skriv.ist",
  "https://comics.skriv.ist",
  "tauri://localhost",
  "http://tauri.localhost",
  "https://tauri.localhost"
]
secure_cookie = true

This list supports the Skrivist macOS and Windows apps with Armarium v0.3.2 or later, too. Replace the corresponding top-level settings in your config, before any [scan], [limits], or [[library]] sections. Use a reverse proxy such as Caddy, Synology’s proxy, or Tailscale Serve for HTTPS.

  1. Restart Armarium.Log in, open Admin → Pair a phone, and choose Books or Comics and a device name.
  2. Scan with your phone’s camera.Open the QR link. The reader’s catalogue address is filled in for you.
  3. Tap Connect. Pick your next read.Browse the catalogue and choose Read book or Read issue. Each pairing has a token you can revoke in Admin.

A home-network or Tailscale server works if the phone is on that network too. Download a title before going offline; wait for the reader’s offline assets to finish caching.

Pairing and connectivity guide
Already have an OPDS reader?

Add https://<your-host>/opds/v1.2/catalog to your OPDS 1.2 reader. Create a token in Admin → API tokens, use any username, and enter the token as the Basic auth password.

For apps without Basic auth, use https://<your-host>/opds/t/<token>/v1.2/catalog. Treat that address as a credential. OPDS clients such as KOReader, Panels, and Chunky can use these feeds; capabilities vary by reader.

All clients and API endpoints

A small server. A full shelf.

More reading. Less running.

Get Armarium