LocalMind v2.0

Offline AI Assistant - Chat with Your Documents. Privately.

No cloud. No API key. No data leaks. Runs 100% on your machine.

Quick Start · Features · Tech Stack · Troubleshooting · Contributing · Screenshots

What's New in v2.0

Feature	Description
Streaming Responses	See AI reply token-by-token in real time
Plugin System	Calculator, Word Counter, JSON Formatter, Code Runner, Summarizer
8 Languages	English, Hindi, Tamil, Telugu, Kannada, French, German, Spanish
Export Chats	Download conversations as Markdown, JSON, or TXT
Session Manager	Full CRUD - create, rename, search, delete chat sessions
Settings Panel	Temperature, RAG chunks, model, theme, language
Docker v2	Health checks, persistent volumes, nginx reverse proxy
30+ Tests	Full pytest suite with mocked Ollama

All Features

Feature	Status
Fully Offline (Ollama)	Included
PDF / TXT / CSV / DOCX / MD / HTML upload	Included
RAG — Chat with Documents	Included
Streaming Responses (SSE)	Included
Multi-Model (Llama3, Mistral, Phi3, Gemma, DeepSeek)	Included
8 UI Languages	Included
Chat History (SQLite)	Included
Session Manager (CRUD)	Included
Session Search	Included
Plugin System (6 plugins)	Included
Export (MD / JSON / TXT)	Included
Settings Panel	Included
Docker Compose	Included
30+ Tests	Included
Zero telemetry	Included

🛠 Tech Stack

┌────────────────────────────────────────────────┐
│               LocalMind v2.0                   │
├──────────────┬─────────────────────────────────┤
│  Frontend    │  React 18 + Tailwind + Vite     │
│  Backend     │  Python 3.11 + FastAPI          │
│  AI Engine   │  Ollama (local LLM)             │
│  RAG         │  LangChain + ChromaDB           │
│  Embeddings  │  sentence-transformers (local)  │
│  Database    │  SQLite (100% local)            │
│  Streaming   │  Server-Sent Events (SSE)       │
│  Deploy      │  Docker Compose + nginx         │
│  Testing     │  pytest + TestClient            │
└──────────────┴─────────────────────────────────┘

Quick Start

Option 1 - Docker (Recommended, 3 commands)

# 1. Pull a model (one-time, ~4GB)
ollama pull llama3

# 2. Clone and start
git clone https://github.com/yourusername/localmind.git
cd localmind && docker compose up

# 3. Open browser
open http://localhost:3000

Option 2 - Manual Setup

git clone https://github.com/yourusername/localmind.git
cd localmind

# Backend
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp ../.env.example ../.env
uvicorn app:app --reload --port 8000

# Frontend (new terminal)
cd frontend
npm install && npm run dev
# Open http://localhost:3000

Prerequisites: Python 3.11+ | Node 18+ | Ollama | Docker

Render Deploy

If you deploy on Render, set the frontend build to use VITE_API_BASE_URL and configure the backend with CORS_ORIGINS.

# backend service envs
OLLAMA_HOST=http://<your-ollama-host>:11434
DEFAULT_MODEL=llama3
CORS_ORIGINS=https://<your-frontend>.onrender.com

# frontend static site envs
VITE_API_BASE_URL=https://<your-backend>.onrender.com/api

The included render.yaml defines a backend web service and a frontend static site for the same repo.

macOS Install Troubleshooting

`node` or `npm` not found

Symptom: zsh: command not found: node or The engine "node" is incompatible with this module

brew install nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$(brew --prefix nvm)/nvm.sh" ] && . "$(brew --prefix nvm)/nvm.sh"' >> ~/.zshrc
source ~/.zshrc
nvm install 18 && nvm use 18

Open a new terminal window after running this so the PATH update takes effect.

`pip install` fails building wheels

Symptom: xcrun: error: invalid active developer path or clang: error: command not found

xcode-select --install   # one-time, installs Apple Command Line Tools

cd backend
python3 -m venv venv && source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

If the popup says tools are already installed, run xcode-select -p to confirm the path, then retry pip.

Apple Silicon architecture mismatch

Symptom: bad CPU type in executable or mach-o file, but is an incompatible architecture

cd backend
rm -rf venv
arch -arm64 python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cd ../frontend
arch -arm64 npm install

If your Python or Node was installed under Intel Homebrew, open a Rosetta shell first (arch -x86_64 zsh) and rerun the same commands there.

Port 3000 or 8000 already in use

Symptom: EADDRINUSE: address already in use

lsof -ti :3000 | xargs kill
lsof -ti :8000 | xargs kill

Then re-run npm run dev and uvicorn app:app --reload --port 8000.

Ollama not reachable

Symptom: Failed to connect to Ollama or Connection refused — localhost:11434

ollama serve
ollama pull llama3
curl http://localhost:11434/api/tags   # should return a JSON list of models

If ollama is not found, download the app from ollama.com and reopen Terminal.

Python version too old

Symptom: python --version shows 3.10 or earlier

brew install python@3.11

cd backend
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Run python --version inside the activated venv — it should show 3.11.x.

Verifying Your macOS Setup

node --version      # v18.x or v20.x
npm --version       # 8 or higher
python3 --version   # Python 3.11.x or higher
ollama list         # shows llama3 or another pulled model

If all four pass and npm run dev starts without errors, your setup is complete.

Project Structure

localmind/
├── backend/
│   ├── app.py                    # FastAPI entry point
│   ├── routes/
│   │   ├── chat.py               # /api/chat — streaming + standard
│   │   ├── sessions.py           # /api/sessions — full CRUD
│   │   ├── upload.py             # /api/upload — file indexing
│   │   ├── models.py             # /api/models — Ollama management
│   │   ├── plugins.py            # /api/plugins — 6 built-in plugins
│   │   ├── export.py             # /api/export — MD, JSON, TXT
│   │   └── settings.py           # /api/settings — app config
│   ├── services/
│   │   ├── rag_service.py        # LangChain + ChromaDB RAG
│   │   ├── ollama_service.py     # Ollama + streaming
│   │   └── db_service.py        # SQLite — all CRUD
│   ├── models/
│   │   └── schemas.py           # Pydantic v2 schemas
│   ├── tests/
│   │   └── test_api.py          # 30+ tests
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── App.jsx               # Root — state, routing
│   │   ├── components/
│   │   │   ├── ChatWindow.jsx    # Messages + streaming + export
│   │   │   ├── Sidebar.jsx       # Sessions + model + language
│   │   │   ├── StatusBar.jsx     # Header toolbar
│   │   │   ├── UploadPanel.jsx   # Drag-drop file upload
│   │   │   ├── PluginsPanel.jsx  # Plugin runner UI
│   │   │   └── SettingsPanel.jsx # Settings form
│   │   └── utils/
│   │       └── api.js            # All backend API calls
│   ├── package.json
│   ├── vite.config.js
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
├── README.md
├── CONTRIBUTING.md
└── ROADMAP.md

Plugins

Plugin	Description
Calculator	Safe math evaluator (supports `sqrt`, `log`, `sin`, etc.)
Summarizer	Extractive summary of long text
Word Counter	Words, chars, sentences, paragraphs
{} JSON Formatter	Validate and pretty-print JSON
Code Runner	Run Python snippets in a sandbox
Translator	Language detection + translation via LocalMind

Running Tests

cd backend
pip install pytest pytest-asyncio
pytest tests/ -v
# 30+ tests covering: sessions, chat, plugins, upload, export, settings

🤝 Contributing

Fork → Clone → Create branch (git checkout -b feature/your-feature)
Make changes → Write tests → Commit (git commit -m "feat: ...")
Push → Open Pull Request

Issues labeled good-first-issue are perfect for beginners!

Read CONTRIBUTING.md for the full guide.

License

If LocalMind helped you, please star the repo. ⭐✨🚀

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

LocalMind v2.0

Offline AI Assistant - Chat with Your Documents. Privately.

What's New in v2.0

All Features

🛠 Tech Stack

Quick Start

Option 1 - Docker (Recommended, 3 commands)

Option 2 - Manual Setup

Render Deploy

macOS Install Troubleshooting

`node` or `npm` not found

`pip install` fails building wheels

Apple Silicon architecture mismatch

Port 3000 or 8000 already in use

Ollama not reachable

Python version too old

Verifying Your macOS Setup

Project Structure

Plugins

Running Tests

🤝 Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 82 Commits
.github		.github
backend		backend
docs		docs
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
README.md		README.md
ROADMAP.md		ROADMAP.md
docker-compose.yml		docker-compose.yml
render.yaml		render.yaml
runtime.txt		runtime.txt

Folders and files

Latest commit

History

Repository files navigation

LocalMind v2.0

Offline AI Assistant - Chat with Your Documents. Privately.

What's New in v2.0

All Features

🛠 Tech Stack

Quick Start

Option 1 - Docker (Recommended, 3 commands)

Option 2 - Manual Setup

Render Deploy

macOS Install Troubleshooting

node or npm not found

pip install fails building wheels

Apple Silicon architecture mismatch

Port 3000 or 8000 already in use

Ollama not reachable

Python version too old

Verifying Your macOS Setup

Project Structure

Plugins

Running Tests

🤝 Contributing

License

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`node` or `npm` not found

`pip install` fails building wheels

Packages