Skip to content
Back to search

minima

On-premises conversational RAG with configurable containers

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/minima-ai-inc--minima/badge.svg)](/listings/minima-ai-inc--minima)

HTML

<a href="/listings/minima-ai-inc--minima"><img src="/api/listings/minima-ai-inc--minima/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The easiest way to start Minima is using the `run.sh` script:

./run.sh

You'll see the following options:

Select an option:
1) Fully Local Setup (Ollama)
2) Custom LLM (OpenAI-compatible API)
3) ChatGPT Integration
4) MCP usage
5) Quit

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 212 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <a href="https://mnma.ai/" target="blank"><img src="assets/logo-full.svg" width="300" alt="MNMA Logo" /></a>
  3. </p>
  4. **Minima** is an open source RAG on-premises containers, with ability to integrate with ChatGPT and MCP.
  5. Minima can also be used as a fully local RAG or with your own deployed LLM.
  6. Minima currently supports four modes:
  7. 1. **Isolated installation (Ollama)** – Operate fully on-premises with containers, free from external dependencies such as ChatGPT or Claude. All neural networks (LLM, reranker, embedding) run on your cloud or PC, ensuring your data remains secure.
  8. 2. **Custom LLM (OpenAI-compatible API)** – Use your own deployed LLM with OpenAI-compatible API (vLLM, Ollama server, TGI, etc.). The indexer runs locally while the LLM can be on your server, cloud, or local machine. No Ollama deployment needed, lighter resource usage, and full control over your LLM infrastructure.
  9. 3. **Custom GPT** – Query your local documents using ChatGPT app or web with custom GPTs. The indexer runs on your cloud or local PC, while the primary LLM remains ChatGPT.
  10. 4. **Anthropic Claude** – Use Anthropic Claude app to query your local documents. The indexer operates on your local PC, while Anthropic Claude serves as the primary LLM.
  11. ---
  12. ## Running as Containers
  13. ### Quick Start with run.sh
  14. The easiest way to start Minima is using the `run.sh` script:
  15. ```bash
  16. ./run.sh
  17. ```
  18. You'll see the following options:
  19. ```
  20. Select an option:
  21. 1) Fully Local Setup (Ollama)
  22. 2) Custom LLM (OpenAI-compatible API)
  23. 3) ChatGPT Integration
  24. 4) MCP usage
  25. 5) Quit
  26. ```
  27. ### Manual Docker Compose Commands
  28. 1. Create a .env file in the project's root directory (where you'll find .env.sample). Place .env in the same folder and copy all environment variables from .env.sample to .env.
  29. 2. Ensure your .env file includes the following variables:
  30. <ul>
  31. <li> LOCAL_FILES_PATH </li>
  32. <li> EMBEDDING_MODEL_ID </li>
  33. <li> EMBEDDING_SIZE </li>
  34. <li> OLLAMA_MODEL (only for Ollama mode) </li>
  35. <li> RERANKER_MODEL (only for Ollama mode) </li>
  36. <li> LLM_BASE_URL (only for Custom LLM mode) </li>
  37. <li> LLM_MODEL (only for Custom LLM mode) </li>
  38. <li> LLM_API_KEY (optional for Custom LLM mode) </li>
  39. <li> USER_ID </li> - required for ChatGPT integration, just use your email
  40. <li> PASSWORD </li> - required for ChatGPT integration, just use any password
  41. </ul>
  42. 3. For fully local installation use: **docker compose -f docker-compose-ollama.yml --env-file .env up --build**.
  43. 4. For custom LLM deployment (OpenAI-compatible API) use: **docker compose -f docker-compose-custom-llm.yml --env-file .env up --build**.
  44. 5. For ChatGPT enabled installation use: **docker compose -f docker-compose-chatgpt.yml --env-file .env up --build**.
  45. 6. For MCP integration (Anthropic Desktop app usage): **docker compose -f docker-compose-mcp.yml --env-file .env up --build**.
  46. 6. In case of ChatGPT enabled installation copy OTP from terminal where you launched docker and use [Minima GPT](https://chatgpt.com/g/g-r1MNTSb0Q-minima-local-computer-search)
  47. 7. If you use Anthropic Claude, just add folliwing to **/Library/Application\ Support/Claude/claude_desktop_config.json**
  48. ```
  49. {
  50. "mcpServers": {
  51. "minima": {
  52. "command": "uv",
  53. "args": [
  54. "--directory",
  55. "/path_to_cloned_minima_project/mcp-server",
  56. "run",
  57. "minima"
  58. ]
  59. }
  60. }
  61. }
  62. ```
  63. 8. To use fully local installation go to `cd electron`, then run `npm install` and `npm start` which will launch Minima electron app.
  64. 9. Ask anything, and you'll get answers based on local files in {LOCAL_FILES_PATH} folder.
  65. ---
  66. ## Variables Explained
  67. **LOCAL_FILES_PATH**: Specify the root folder for indexing (on your cloud or local pc). Indexing is a recursive process, meaning all documents within subfolders of this root folder will also be indexed. Supported file types: .pdf, .xls, .docx, .txt, .md, .csv.
  68. **EMBEDDING_MODEL_ID**: Specify the embedding model to use. Currently, only Sentence Transformer models are supported. Testing has been done with sentence-transformers/all-mpnet-base-v2, but other Sentence Transformer models can be used.
  69. **EMBEDDING_SIZE**: Define the embedding dimension provided by the model, which is needed to configure Qdrant vector storage. Ensure this value matches the actual embedding size of the specified EMBEDDING_MODEL_ID.
  70. **OLLAMA_MODEL**: Set up the Ollama model, use an ID available on the Ollama [site](https://ollama.com/search). Please, use LLM model here, not an embedding. This is only required when using Ollama (not needed when using custom LLM).
  71. **LLM_BASE_URL**: (Optional) Base URL for your custom OpenAI-compatible LLM API endpoint. When this is set, Ollama will not be used and you don't need to deploy it.
  72. **LLM_MODEL**: (Optional) Model name for your custom LLM. Required when LLM_BASE_URL is set.
  73. **LLM_API_KEY**: (Optional) API key for your custom LLM. If your LLM doesn't require authentication, you can omit this or set it to any value.
  74. **RERANKER_MODEL**: Specify the reranker model for Ollama mode. Currently, we have tested with BAAI rerankers. You can explore all available rerankers using this [link](https://huggingface.co/collections/BAAI/). **Note:** This is NOT required for Custom LLM mode - the reranker model will not be downloaded if you're using LLM_BASE_URL.
  75. **USER_ID**: Just use your email here, this is needed to authenticate custom GPT to search in your data.
  76. **PASSWORD**: Put any password here, this is used to create a firebase account for the email specified above.
  77. ---
  78. ## Examples
  79. **Example of .env file for on-premises/local usage with Ollama:**
  80. ```
  81. LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
  82. EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
  83. EMBEDDING_SIZE=768
  84. OLLAMA_MODEL=qwen2:0.5b # must be LLM model id from Ollama models page
  85. RERANKER_MODEL=BAAI/bge-reranker-base # please, choose any BAAI reranker model
  86. ```
  87. **Example of .env file for custom LLM deployment (OpenAI-compatible API):**
  88. ```
  89. LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
  90. EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
  91. EMBEDDING_SIZE=768
  92. LLM_BASE_URL=http://your-llm-address:port/v1 # Your custom LLM endpoint
  93. LLM_MODEL=Qwen/Qwen-1.7B # Your model name
  94. LLM_API_KEY=not-needed # Optional: API key if required
  95. # NOTE: OLLAMA_MODEL and RERANKER_MODEL are NOT needed for custom LLM mode
  96. # The Docker build will skip reranker download automatically
  97. ```
  98. **Important:** When using custom LLM mode, you do NOT need to set `OLLAMA_MODEL` or `RERANKER_MODEL` variables. The custom LLM workflow uses direct retrieval without reranking for better performance. The Dockerfile will automatically skip downloading the reranker model during build.
  99. To use a chat ui, please navigate to **http://localhost:3000**
  100. The custom LLM mode uses a different workflow compared to Ollama:
  101. **Ollama Workflow:**
  102. 1. User query → Query enhancement (LLM call)
  103. 2. Document retrieval with reranking (HuggingFace CrossEncoder)
  104. 3. Answer generation (LLM call)
  105. **Custom LLM Workflow:**
  106. 1. User query → LLM decides if document search is needed (function calling)
  107. 2. If needed: Direct vector search (no reranking)
  108. 3. LLM generates answer with or without retrieved context
  109. **Compatible LLM Servers:**
  110. - **vLLM** - High-performance inference server (`http://your-server:8000/v1`)
  111. - **Text Generation Inference (TGI)** - Hugging Face's inference server
  112. - **Ollama Server** - Ollama running in API mode
  113. - **LiteLLM** - Proxy for multiple LLM providers
  114. - **LocalAI** - OpenAI-compatible local inference
  115. - **OpenAI API** - Directly use OpenAI's API
  116. - **Any OpenAI-compatible endpoint**
  117. This will automatically use `docker-compose-custom-llm.yml` which deploys only the necessary services (no Ollama container).
  118. **Example of .env file for Claude app:**
  119. ```
  120. LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
  121. EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
  122. EMBEDDING_SIZE=768
  123. ```
  124. For the Claude app, please apply the changes to the claude_desktop_config.json file as outlined above.
  125. **To use MCP with GitHub Copilot:**
  126. 1. Create a .env file in the project’s root directory (where you’ll find env.sample). Place .env in the same folder and copy all environment variables from env.sample to .env.
  127. 2. Ensure your .env file includes the following variables:
  128. - LOCAL_FILES_PATH
  129. - EMBEDDING_MODEL_ID
  130. - EMBEDDING_SIZE
  131. 3. Create or update the `.vscode/mcp.json` with the following configuration:
  132. ````json
  133. {
  134. "servers": {
  135. "minima": {
  136. "type": "stdio",
  137. "command": "path_to_cloned_minima_project/run_in_copilot.sh",
  138. "args": [
  139. "path_to_cloned_minima_project"
  140. ]
  141. }
  142. }
  143. }
  144. ````
  145. **Example of .env file for ChatGPT custom GPT usage:**
  146. ```
  147. LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
  148. EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
  149. EMBEDDING_SIZE=768
  150. USER_ID=user@gmail.com # your real email
  151. PASSWORD=password # you can create here password that you want
  152. ```
  153. Also, you can run minima using **run.sh**.
  154. ---
  155. **For MCP usage, please be sure that your local machines python is >=3.10 and 'uv' installed.**
  156. Minima (https://github.com/dmayboroda/minima) is licensed under the Mozilla Public License v2.0 (MPLv2).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.