kotaemon

What it is

kotaemon is Cinnamon’s open source web app for asking questions about your own documents. You upload files, it indexes them for full-text and vector search, and a language model answers from the passages it finds. Each answer carries citations. You can open a cited passage in the PDF viewer inside the browser, highlighted, with its relevance score. Developers can also use it as a framework for their own RAG pipeline, with a Gradio UI already built.

1. You upload files on the File Index tab
2. kotaemon splits them and indexes text and vectors
3. A question pulls passages by keywords and meaning
4. Re-ranking and scores sort the evidence
5. The model answers and cites the passages it used

Who it suits

People who want to ask questions of papers, reports or manuals in a browser and check each answer against the page it came from. With a local model through Ollama, your documents stay on your machine. Python developers who want a RAG pipeline with a ready interface can add their own reasoning or indexing pipelines.

Skip it for now if you want a server that several people share over a network. The latest release has open reports of code execution with no login and of users reaching each other’s chats.

Where to use it

kotaemon is a web app you open in a browser, and the docs give these ways to run it.

• Docker, in a full, lite or Ollama image, for linux/amd64 and linux/arm64
• The release zip, with install scripts for Windows, macOS and Linux
• From source with uv or conda, on Python 3.10 or newer
• Your own Hugging Face Space, copied from the maker’s template
• The maker’s two live demos on Hugging Face, and a Colab notebook for local RAG

Out of the box it reads .pdf, .html, .mhtml and .xlsx files. The full Docker image, or Unstructured on a source install, adds more types such as .doc and .docx.

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with a file for each route, for models and for the login. The README recommends Docker, and its command for the full image is below.

1. Run the full image with Docker. Run it in a folder where it can make ktem_app_data, which holds all of the app’s data.
2. Open localhost:7860 in your browser. The README gives http://localhost:7860/ as the address.
3. Log in as admin, password admin. Change the password in the Settings tab right away, as the user guide says.
4. Add a chat and an embedding model. On the Resources tab, add one under LLMs and one under Embedding Models, and set each as the default.
5. Upload files on the File Index tab. Click Upload and Index, and wait for the message that says it is done.

docker run \
-e GRADIO_SERVER_NAME=0.0.0.0 \
-e GRADIO_SERVER_PORT=7860 \
-v ./ktem_app_data:/app/ktem_app_data \
-p 7860:7860 -it --rm \
ghcr.io/cinnamon/kotaemon:main-full

For the lite image, or the one with Ollama bundled, change only the image name to main-lite or main-ollama. Without Docker, download kotaemon-app.zip from the latest release, unzip it and run the script for your system in its scripts folder.

How to use it

The Chat tab has three panels. In the conversation settings panel you pick or start a conversation and choose which files it searches: Disabled, Search All, or Select for a few you name. The chat panel is where you talk to the model. The information panel shows the evidence behind each answer, with the cited text highlighted and a score beside each passage.

• Answer confidence: the model’s own confidence in its answer
• Relevance score: the overall match between a passage and your question, taken by default from the LLM relevant score
• Vectorstore score: the embedding similarity. It shows full-text search when the passage came from the full-text index
• LLM relevant score: a model’s judgment of how well the passage fits the question
• Reranking score: from Cohere’s reranking model

The Usage page rates the LLM relevant score as the most reliable, then the reranking score, then the vector score. Evidence is sorted by overall relevance and by whether it was cited. The README says most retrieval and generation steps, prompts included, can be changed in the settings UI.

Example

You keep the manual for your office printer as a PDF. You upload it on the File Index tab. In the Chat tab you set the file list to Select, pick the manual, and type:

How do I clear a paper jam in the rear tray?

The answer comes back with citations. The information panel lists the passages it drew on, each with its relevance score, and highlights the sentences it cited. You can open a citation in the PDF viewer and read the passage in place. If retrieval finds only weak matches, kotaemon shows a warning.

For newcomers and experts

If you are new. RAG means a model answers from passages found in your own files, not only from what it learned in training. kotaemon does the finding. It splits each file into segments, stores them, and returns the best matches for each question. The scores tell you how far to trust each passage. Start small. Try the lite image with one API key, or the Ollama image if your files must stay local, and upload a few files you know well. The Usage page says local models are private and free but answer less well, and run only as fast as your hardware.

For experts. The repository holds two Python packages: libs/kotaemon, the library you import, and libs/ktem, the app built on it. flowsettings.py picks the document store for full-text search (Elasticsearch, LanceDB or SimpleFileDocumentStore) and the vector store (ChromaDB, LanceDB, InMemory, Milvus or Qdrant). It also lists the reasoning pipelines the UI offers.

KH_REASONINGS = [
    "ktem.reasoning.simple.FullQAPipeline",
    "ktem.reasoning.simple.FullDecomposeQAPipeline",
    "ktem.reasoning.react.ReactAgentPipeline",
    "ktem.reasoning.rewoo.RewooAgentPipeline",
]

To add your own, put a new .py file in libs/ktem/ktem/reasoning/ and list it there. A custom indexing pipeline starts from the sample in libs/ktem/ktem/index/file/graph. The default indexing pipeline reads each file, splits it and embeds each segment. It keeps the vectors in a vector store and the text in a document store. A Source table lists the files, and an Index table links each file to its entries in both stores.

For graphs, the README recommends NanoGraphRAG (USE_NANO_GRAPHRAG=true) to most users, and also offers LightRAG (USE_LIGHTRAG=true). It says Microsoft’s GraphRAG indexing works only with the OpenAI or Ollama API, and pins it to graphrag<=0.3.6. The first two can bring version conflicts, which issue #440 covers. On Docker, a local model on the host is reached at host.docker.internal instead of localhost.

Good to know

Read the first point before anyone else can reach the app.

• Security, as of 3 November 2026: v0.12.0 from 31 May 2026 is the latest release, and the National Vulnerability Database lists three reports against it. VulnCheck rates CVE-2026-69098 critical: code execution with no login, through the check_connection endpoint. CVE-2026-82281 and CVE-2026-86867 describe chat functions that skip the owner check, so other users can read, rename or delete your conversations. Issues #844 and #846 hold the reporters’ proofs of concept, with no reply or linked fix. Run it for yourself, on your own machine, until a release fixes them
• Login: the README and the Getting Started page give admin / admin as the default login, and issue #846 says it is set in flowsettings.py. Change it at the first login
• Your data: everything lives in the ktem_app_data folder, which you can back up or copy to a new machine. Your questions and the matching passages go to the model you set up, unless it runs locally. Cohere reranking, Azure Document Intelligence and Adobe PDF Extract are outside services too
• The .env file: the models set in it fill the app’s database once, on the first run. After that, change models on the Resources tab. Other lines, such as GRAPHRAG_API_KEY, PADDLE_DEVICE and KH_VLM_ENDPOINT, stay in use as settings
• Platforms: the maker tests the Docker images on linux/amd64 and linux/arm64. The zip installer stops when its folder path has a space in it. The macOS and Linux scripts run only on x86_64 or arm64, and the Windows script installs the x86_64 Miniconda
• Removal: the docs give no uninstall steps. Mindket’s notes say what the Docker and zip routes leave, so you can take them out by hand
• License: Apache-2.0. The LICENSE file is the standard text and names no copyright holder