How to use Quivr: install, run locally and search content

What Quivr does and who it is for

Quivr stores every version of each document, makes it searchable within seconds, and records new documents that match a topic you follow. Your application talks to it over an HTTP API. Quivr has no user interface of its own, so the quickstart and the optional demo web app are the only ready-made ways to see it working.

It suits developers building a search or monitoring pipeline over a stream of documents, and teams evaluating a self-hosted, plugin-based ingestion and search engine. It is not a ready-made chat or end-user app.

• Collect documents one by one, in batches, or pulled from sources on a schedule
• Search by keywords, by meaning, or both, with results pointing to the exact passage and version
• Save alerts as a keyword expression or a plain-language description
• Extend file formats, sources, embedding models, ranking and alert rules with plugins

Check the requirements before you install

Quivr runs on Linux on x86_64 or on a Mac with Apple Silicon. Windows and Intel Macs are not listed as supported. You also need Docker with Compose v2, the Go version named in the repository's go.mod file, Python 3.12 with venv, and jq. The first start downloads about 1 GB.

• Linux x86_64 or macOS on Apple Silicon
• Docker with Compose v2
• The Go version listed in go.mod
• Python 3.12 with venv
• jq

Install and start Quivr locally

Quivr is installed by cloning the repository and building it, not from a package manager. Clone the repository, then start Quivr and its dependencies in Docker. The second command points your current shell at the API using a local key.

make dev starts Quivr and its dependencies in Docker. The quickstart then walks you through creating a collection, adding an article, and searching for it.

Try search, alerts and the demo web app

Follow the Quickstart on the documentation site. It covers creating a collection, adding an article, finding it by keyword and by meaning, and getting alerted on a topic, in about fifteen minutes.

If you want a visual front end on top of the API, make demo starts a web app at http://127.0.0.1:5183. Its code lives in the quivr-search folder.

• Create a collection, add an article, then search by keyword and by meaning
• Save an alert and check that new matching documents are recorded with the reason
• Use the demo web app to browse results if you prefer a screen over API calls

Run the checks and contribute

Run make check before pushing changes. It takes about two minutes and needs no Docker. make verify runs the end-to-end journeys on an isolated stack.

Read AGENTS.md for the rules and CONTEXT.md for the domain vocabulary before contributing. Pull request titles follow Commitizen, for example feat(ingestion): accept record versions. Report security issues privately, as described in SECURITY.md.

Know the current status before you rely on it

Quivr 2 keeps the HTTP API under /v0 compatible across 2.x releases, and upgrades keep your data in place, according to the README. The project analysis describes Quivr as being at an evaluation stage and not yet ready for production, and the API is described as v0 that may change. Read the Known limits page before building anything you cannot afford to rework.