Quick Start with run.sh

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

Manual Docker Compose Commands

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.

2. Ensure your .env file includes the following variables:

• LOCAL_FILES_PATH
• EMBEDDING_MODEL_ID
• EMBEDDING_SIZE
• OLLAMA_MODEL (only for Ollama mode)
• RERANKER_MODEL (only for Ollama mode)
• LLM_BASE_URL (only for Custom LLM mode)
• LLM_MODEL (only for Custom LLM mode)
• LLM_API_KEY (optional for Custom LLM mode)
• USER_ID
- required for ChatGPT integration, just use your email
• PASSWORD
- required for ChatGPT integration, just use any password

3. For fully local installation use: docker compose -f docker-compose-ollama.yml --env-file .env up --build.

4. For custom LLM deployment (OpenAI-compatible API) use: docker compose -f docker-compose-custom-llm.yml --env-file .env up --build.

5. For ChatGPT enabled installation use: docker compose -f docker-compose-chatgpt.yml --env-file .env up --build.

6. For MCP integration (Anthropic Desktop app usage): docker compose -f docker-compose-mcp.yml --env-file .env up --build.

7. In case of ChatGPT enabled installation copy OTP from terminal where you launched docker and use Minima GPT

8. If you use Anthropic Claude, just add folliwing to /Library/Application\ Support/Claude/claude_desktop_config.json

{
    "mcpServers": {
      "minima": {
        "command": "uv",
        "args": [
          "--directory",
          "/path_to_cloned_minima_project/mcp-server",
          "run",
          "minima"
        ]
      }
    }
  }

8. To use fully local installation go to cd electron, then run npm install and npm start which will launch Minima electron app.

9. Ask anything, and you'll get answers based on local files in {LOCAL_FILES_PATH} folder.

The Docker build will skip reranker download automatically

**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.

To use a chat ui, please navigate to **http://localhost:3000**

The custom LLM mode uses a different workflow compared to Ollama:

**Ollama Workflow:**
1. User query → Query enhancement (LLM call)
2. Document retrieval with reranking (HuggingFace CrossEncoder)
3. Answer generation (LLM call)

**Custom LLM Workflow:**
1. User query → LLM decides if document search is needed (function calling)
2. If needed: Direct vector search (no reranking)
3. LLM generates answer with or without retrieved context

**Compatible LLM Servers:**
- **vLLM** - High-performance inference server (`http://your-server:8000/v1`)
- **Text Generation Inference (TGI)** - Hugging Face's inference server
- **Ollama Server** - Ollama running in API mode
- **LiteLLM** - Proxy for multiple LLM providers
- **LocalAI** - OpenAI-compatible local inference
- **OpenAI API** - Directly use OpenAI's API
- **Any OpenAI-compatible endpoint**

This will automatically use `docker-compose-custom-llm.yml` which deploys only the necessary services (no Ollama container).

**Example of .env file for Claude app:**

LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/ EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2 EMBEDDING_SIZE=768

For the Claude app, please apply the changes to the clau