No cloud. No API key. No data leaks. Runs 100% on your machine.
Quick Start · Features · Tech Stack · Troubleshooting · Contributing · Screenshots
| 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 |
| 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 |
┌────────────────────────────────────────────────┐
│ 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 │
└──────────────┴─────────────────────────────────┘
# 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:3000git 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:3000Prerequisites: Python 3.11+ | Node 18+ | Ollama | Docker
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/apiThe included render.yaml defines a backend web service and a frontend static site for the same repo.
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 18Open a new terminal window after running this so the PATH update takes effect.
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.txtIf the popup says tools are already installed, run
xcode-select -pto confirm the path, then retry pip.
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 installIf your Python or Node was installed under Intel Homebrew, open a Rosetta shell first (
arch -x86_64 zsh) and rerun the same commands there.
Symptom: EADDRINUSE: address already in use
lsof -ti :3000 | xargs kill
lsof -ti :8000 | xargs killThen re-run
npm run devanduvicorn app:app --reload --port 8000.
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 modelsIf
ollamais not found, download the app from ollama.com and reopen Terminal.
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.txtRun
python --versioninside the activated venv — it should show3.11.x.
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 modelIf all four pass and npm run dev starts without errors, your setup is complete.
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
| 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 |
cd backend
pip install pytest pytest-asyncio
pytest tests/ -v
# 30+ tests covering: sessions, chat, plugins, upload, export, settings- 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.
MIT © 2026
If LocalMind helped you, please star the repo. ⭐✨🚀
Built something cool with LocalMind? We'd love to see it! Open a Pull Request to add your project, tutorial, or integration to this list.
- [Community projects will appear here.] - A brief 1-2 sentence description of what your integration does. (By @yourusername)
- Contributions welcome! Add your tool here.
- Have you written a blog post or recorded a video setup guide? Share it with the community here!