Papers, for us. A research library for groups, on your own server, read with the AI assistant you already use. Made by scientists, for scientists.
Homepage and demo (a recorded library to look around in: uploads, changes and search by meaning don't work there).
Status: beta (0.1.5), in a pilot. It works, with private papers and nested groups, but the data format may still change. See the changelog for what is there and what is missing.
- AI first, on your terms: no built-in chatbot and no AI vendor. Any assistant (Claude, ChatGPT, a self-hosted or local model) connects through an MCP server, sees only what the user may see, cites the exact passage and asks before it changes anything: retrieval-augmented generation (RAG) over your own papers. paperus finds, checks and keeps track; the assistant does the thinking.
- One library for the group, on your own server with your organisation's login (OIDC), groups inside groups, plus private space for each member.
- Semantic search: search by meaning across the full text of every paper, note and annotation, together with keyword search, computed on the server with small open models (and reranked, on a GPU).
- Figure search: figures and tables are found by their captions and shown in the results, opening the paper at the figure. With a GPU, multimodal search finds them by what they show too (a heatmap with a ring, two crossing bands): one switch for the administrator.
- PDFs that fit your phone: fluent mode turns two columns into one, figures whole, highlights and notes as on the page.
- Preprints that get published: the published version is found by itself, and cited from then on.
- Apps for Linux, Windows and macOS, also offline: your libraries in a window of their own. Offline, the app opens its copy: papers kept with their PDFs ("Keep offline on this device", for a paper or a whole collection), annotations and notes made on the train sent when you are back. Or a library on the computer itself, without a server. Notifications, PDFs added with "Open with"; installers on each release. Android and iOS are planned.
- Sources first: papers, lecture notes, meeting notes and their versions, with notes and annotations attached to them. Not a general notes app.
- No lock-in: full export of files, BibTeX/CSL-JSON, Markdown notes and annotations at any time.
- And the rest: import, export, OCR, tags, collections, smart collections, annotations, notes, duplicates, open-access PDFs, authors with ORCID, references and cited-by, similar papers, browser extension, backups, monitoring.
- Free and open source, forever: Apache-2.0, no paid tier, no account with us; your server, your data.
Needs a Linux machine (x86-64) with Docker Engine and its Compose plugin
(docker compose), about 4 GB of RAM (the model for search by meaning takes
2–3 GB), and HTTPS out to the internet (the model, metadata services; behind
a proxy, see operations).
- Download
deploy/compose.yamlanddeploy/example.envinto a new folder; renameexample.envto.env. - In
.env, set the folders for files, database, backups and models (CONTACT_EMAIL, which metadata services ask for, can also be given later under Administration → Settings → Server). Random secrets forDB_PASSWORDandML_TOKENin one go:sed -i "s/^DB_PASSWORD=.*/DB_PASSWORD=$(openssl rand -hex 16)/; s/^ML_TOKEN=.*/ML_TOKEN=$(openssl rand -hex 32)/" .env - Put a reverse proxy with HTTPS in front of port 8000, on a (sub)domain of its
own; examples for Caddy and nginx are in
operations. The port is open to this
machine only; with the proxy on another one, set
PAPERUS_PORT=8000. Folders on a network share must belong to uid 1000 there (the containers' user). - Start:
docker compose up -d. The ML service downloads its models when it first needs them (the recommended search model about 300 MB). - Open paperus at its address (the proxy's) in the browser: create the administrator account, or restore a backup found in the backup folder (for moving to a new server). Check the address under Administration → Settings → Server ("Public address"). The library page then lists the first steps: backups, adding people, the browser extension, connecting an AI assistant.
- Optional: people log in with your organisation's accounts (OIDC login), see operations.
Just trying it out, without HTTPS? Open http://localhost:8000 on the same
machine; from another computer on the network, set COOKIE_SECURE=false in
.env first (the login cookie is otherwise sent over HTTPS only).
Backups of the database run every night from the start; add the files (the
PDFs), or change when, under Administration → Backups. They go into
BACKUP_LOCATION on another disk; restoring is described in
operations. To update (see
operations):
docker compose pull && docker compose up -d; the database is brought up
to date as the server starts.
Browser extension (Chrome, Firefox): one click saves the paper you are reading, with its PDF, or the PDF you have open; right-click it to save to another owner; on arXiv, a button next to each paper. For Firefox on addons.mozilla.org; for Chrome and Edge, until it is in their store, load it from the release's zips: see extension/README.md.
| Document | Contents |
|---|---|
| Architecture | Components, stack, data model, scaling |
| Ingestion | Adding items, metadata, PDFs, browser extension, versions, other sources |
| Export | Taking everything home: a SQLite database and the files, in zips; importing it back |
| Search | Chunking, embeddings, hybrid search, deduplication across versions, pgvector |
| Permissions | Who may do what with papers, tags, collections and groups |
| AI integration | MCP tools, permissions, the AI inbox, skill draft |
| Apps | One app for computers and phones (begun), a library on one's computer, offline sync |
| Operations | Hosting at the university, data protection, lessons from similar projects |
| Decisions | Decisions made so far and open questions |
| Pilot | Pilot plan and questions for testers |
Planned work, ideas and bugs are in the issues; labels show the area and whether a point still needs discussion.
Needs Docker, uv and Node.js.
docker compose up -d # Postgres with pgvector on localhost
cd server
uv run alembic upgrade head
uv run paperus user create alice --admin # asks for a password
uv run paperus serve --reload # API on http://localhost:8000
uv run paperus worker # background jobs, in a second terminal
cd ml # machine learning service (search by meaning)
PAPERUS_ML_CACHE_PATH=../data/model-cache uv run paperus-ml
# or in a container, with the same model folder:
# docker compose --profile ml up -d
cd web
npm install
npm run dev # website on http://localhost:5173
npm run api # after API changes: regenerate the clientTo try it from a phone on the same network: start the API with
PAPERUS_COOKIE_SECURE=false (plain HTTP outside localhost) and the website
with npm run dev -- --host 0.0.0.0, then open http://<this PC's IP>:5173.
npm run build writes the website to web/build, which paperus serve
serves on its own port as well. Checks: uv run pytest, uvx pre-commit run --all-files.
The app for computers (Tauri, Rust) is in app/ (app/README.md);
its installers for Linux, Windows and macOS are on each
release. The homepage is in
site/, its demo in e2e/demo/ (README).
Apache-2.0, see LICENSE. Bundled fonts and libraries keep their own licences, see THIRD_PARTY.md.