Skip to content
Get packs

Guide · Open source

How to use serviette: set up a no-code RAG server

Updated · written with AI from the project's own documentation and checked against our catalogue data

serviette is an open-source, no-code RAG server. You point it at a folder of documents, and it serves a chat page and a REST API that answer questions from those documents and cite their sources. This guide shows you how to install it, run the demo, configure it over your own files, and query it. Along the way it covers what the README says about licensing, requirements and current limits.

serviettepathwaycom/serviette · ★ 58.7k · MIT

Quick start

  1. 1Check your pip version. Upgrade pip to version 23.1 or newer before installing, as the README recommends.
  2. 2Install serviette. Run pip install serviette to install it from PyPI.
  3. 3Get a free license key. Sign in at the Pathway license page and copy your free key.
  4. 4Set the license key. Export the key as PATHWAY_LICENSE_KEY in your shell.
  5. 5Run the demo. Run serviette demo with your chosen embedder and open http://localhost:8989.
  6. 6Generate your config. Run serviette wizard to create a config file for your own documents.
  7. 7Start the stack and query it. Run serviette up --config config.yaml, then open the chat or POST to /api/v1/retrieve.

What serviette does and who it suits

serviette runs a question-answering chat and a REST API over a folder of documents, so answers cite their sources. You configure it with one YAML file and a couple of commands. When a document is edited, added or deleted, the answers update within seconds, with no re-upload step.

It suits teams that want a chat over internal documents without writing code, developers who want a quick local RAG prototype with DuckDB as the default store, and anyone who needs a REST retrieval endpoint with a built-in chat page. It is not built for users who need conversation memory or user accounts, since the README says these are not built in yet, or for teams that want a hosted service.

  • Good fit: no-code chat over internal documents
  • Good fit: local RAG prototype with DuckDB by default
  • Good fit: documents that change often and must stay current
  • Not a fit yet: conversation memory or user accounts
  • Not a fit yet: a hosted service (none is listed)

Install serviette and get a Pathway license key

Install serviette from PyPI with pip. The README asks for pip 23.1 or newer, because older pip versions lack resolver improvements this dependency tree needs and can take hours.

serviette runs on the Pathway Live Data Framework, which needs a free license key. Get one from the Pathway license page (GitHub or LinkedIn sign-in), then set it in the PATHWAY_LICENSE_KEY environment variable. Every serviette command expects it there.

  • Requirements: Python and pip 23.1 or newer
  • Get a free Pathway license key at pathway.com/framework/get-license
  • Store it in the PATHWAY_LICENSE_KEY environment variable
python -m pip install -U pip pip install serviette export PATHWAY_LICENSE_KEY=...

Run the demo in four commands

The quickest way to see serviette working is the bundled demo. It indexes a small fictional coffee-machine company corpus into ./serviette-demo/docs and opens a chat at http://localhost:8989. The demo command shown uses OpenAI embeddings, so it also needs an OpenAI API key.

While the demo runs, edit or add files in ./serviette-demo/docs. The README says the answers follow within seconds.

  • Chat address: http://localhost:8989
  • Demo corpus: a fictional coffee-machine company
  • Edit files in ./serviette-demo/docs to see answers change
pip install serviette export PATHWAY_LICENSE_KEY=... export OPENAI_API_KEY=sk-... serviette demo --embedder openai

Configure serviette over your own documents

To run serviette over your own files, generate a config with the interactive wizard, then start the indexer and server together with serviette up. The wizard's default embedder is free and local, and it needs the [local] extra. Plain pip install serviette is enough if you embed with OpenAI instead.

OPENAI_API_KEY powers generated answers. Leave it unset to run keyless, in which case answers quote the retrieved snippets. Production deployments run serviette indexer and serviette server separately. serviette up supervises both.

  • serviette wizard generates a config file
  • serviette up --config config.yaml starts the indexer and server
  • Local embeddings: pip install "serviette[local]" (the wizard default)
  • DuckDB is the default vector store, embedded in a single local file
pip install "serviette[local]" --extra-index-url https://download.pytorch.org/whl/cpu export PATHWAY_LICENSE_KEY=... serviette wizard serviette up --config config.yaml

Query serviette with the REST API

The server hosts the web chat UI on / and the versioned REST API under /api/v1 on one port. To retrieve matching passages for a question, send a POST request to the retrieve endpoint with a JSON body containing a query and a k value for how many results to return.

  • Chat UI: http://localhost:8989/
  • Retrieval endpoint: POST /api/v1/retrieve
  • Body fields used in the example: query and k
curl -X POST http://localhost:8989/api/v1/retrieve -H 'Content-Type: application/json' -d '{"query": "how does persistence work?", "k": 5}'

Keep answers current as documents change

serviette watches the source folder through Pathway. An edit, a new file or a deletion is reflected in the vector database, and so in the answers, within seconds. You do not need to re-upload or re-index anything by hand.

The source describes several supported sources, including the local filesystem, Google Drive, S3/MinIO and SharePoint, and eight vector backends: DuckDB, pgvector, Qdrant, Milvus, ChromaDB, Weaviate, Pinecone and MongoDB Atlas Vector Search.

  • Supported stores: DuckDB (default), pgvector, Qdrant, Milvus, ChromaDB, Weaviate, Pinecone, MongoDB Atlas Vector Search
  • Sources include local filesystem, Google Drive, S3/MinIO and SharePoint

What people use it for

  • A no-code chat over internal policy or product documents with cited sources
  • A local RAG prototype using DuckDB as the embedded default store
  • Keeping answers current for a folder of documents that changes often
  • A REST retrieval endpoint that other internal tools can call, alongside the built-in chat page

Frequently asked questions

Is serviette free to use?

serviette is released under the MIT licence. It runs on Pathway, which requires a free Pathway license key, so you need to get that key before running any serviette command. The README notes that local embeddings are free, and the only metered part is the optional model API that writes answers.

What do I need to install serviette?

You need Python and pip 23.1 or newer. Install with pip install serviette, then set PATHWAY_LICENSE_KEY to your free Pathway key. Older pip versions can take hours to resolve the dependencies.

How do I fix a serviette install that takes forever?

The README says older pip versions lack the resolver improvements this dependency tree needs and can take hours. Upgrade pip with python -m pip install -U pip, then run the install again.

Can serviette run without an OpenAI key?

Yes. The README says to omit OPENAI_API_KEY to run keyless, and answers will then quote the retrieved snippets. With the default local embedder, documents and the index stay on your machine or in your chosen database.

What are the alternatives to serviette?

The comparable projects listed for this item are LlamaIndex, LangChain, PrivateGPT and AnythingLLM. serviette differs in that it is configured with one YAML file and no code, and it keeps answers updated as documents change.

Does serviette keep chat history or support user accounts?

Not yet. The README says conversation memory, user accounts and a hosted offering are not built in yet. It answers one question at a time from the current state of the documents.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

serviette suits teams that want a no-code chat or REST retrieval endpoint over documents that change often, and developers who want a quick local prototype with DuckDB. Pick something else if you need conversation memory, user accounts or a hosted service, which the README says are not built in yet, or if you are unwilling to get the free Pathway license key.

Install options & downloads