Every few months an open-source repo stops being a demo and starts being infrastructure you run at home. Khoj is one of them: a personal AI assistant you self-host, point at your own documents, and query from the browser, Obsidian, Emacs, your phone, or WhatsApp — with any LLM you choose, local or cloud.
I read the actual README and the official self-hosting docs so you do not have to: what Khoj is and how popular it really is, how the system works in 4 steps, a quickstart verified against the current docs, real use cases, and an honest list of when NOT to use it.
1. What Is Khoj: Stars, License, and Facts
Khoj (github.com/khoj-ai/khoj) calls itself “your AI second brain.” It is a personal AI app that scales from an on-device assistant to a cloud-scale enterprise deployment. You chat with any local or online LLM — Llama, Qwen, Gemma, Mistral, GPT, Claude, Gemini, DeepSeek — and get answers grounded in the web and your own docs: PDFs, Markdown, Word, Notion, org-mode files, and images.
GitHub stars
~37k stars (verified Sep 3, 2026)
License
AGPL-3.0 — free to self-host
Stack
Docker or pip · Ollama-ready · port 42110
Why it matters
Khoj is one of the few serious open-source assistants built around your own files instead of a chat box. The repo has been actively maintained since 2021, ships desktop, mobile, Obsidian, Emacs, and WhatsApp clients, and lets every query mix private documents with live web research. Treat the star count as a snapshot — but 2.4k+ forks say people actually deploy it.
There are two ways to run it. Self-hosted on your own machine or server: private, unlimited, no paywalled features, data never leaves your network. Or the hosted cloud at app.khoj.dev: zero setup, latest features first, but your docs live on someone else’s server. Same codebase either way, and you can export from cloud to self-hosted with no lock-in.
2. Architecture in 4 Steps
Khoj looks like a chat app, but underneath it is a small RAG platform: five Docker services that index, retrieve, reason, and act. Here is the loop that answers every question.
Step 1 — Index
your files → pgvector
Khoj syncs your vault, Notion workspace, or dropped files and embeds them into PostgreSQL with pgvector. The Obsidian plugin syncs on a schedule; Emacs users get khoj-chat and khoj-search without leaving the editor.
Step 2 — Retrieve
query → docs + web
Each question triggers semantic search over your index, optionally combined with live web results from the bundled SearxNG instance. Research mode goes multi-hop: plan, fire several queries, read the hits, answer with citations.
Step 3 — Reason
context → any LLM
Retrieved chunks plus conversation history go to whatever model you configured — cloud APIs or a local Ollama model like qwen3 or llama3.1. You set the default and the advanced model separately in server chat settings.
Step 4 — Act
agents → automations
Custom agents bind a persona, a scoped knowledge base, and tools — web search, sandboxed Python via Terrarium — to a role. Automations run them on a cron-style schedule: morning briefings, weekly digests, personal newsletters in your inbox.
The mental model that saves you RAM
Think of Khoj as RAG with a schedule: index once, retrieve every query, reason with any model, act on autopilot. The indexer is hungry on first import — 8 GB RAM minimum, 16 GB for local models — so index overnight and thank yourself later.
3. Quickstart: Running Khoj in 30 Minutes
Every command below is copied from the current README and the official self-hosting docs. Docker is the recommended path; pip works when you want a single process. The server listens on port 42110 either way.
Step A — Download the compose file
mkdir ~/.khoj && cd ~/.khoj wget https://raw.githubusercontent.com/khoj-ai/khoj/master/docker-compose.yml
That file orchestrates five services: the Khoj server, PostgreSQL + pgvector, the Terrarium Python sandbox, SearxNG web search, and an optional computer-control desktop.
Step B — Set secrets and your model keys
# environment — pick what you will actually use KHOJ_ADMIN_PASSWORD=choose-something-secure KHOJ_DJANGO_SECRET_KEY=generate-with-openssl-rand-hex-32 OPENAI_API_KEY=sk-... # ANTHROPIC_API_KEY=sk-ant-... # GEMINI_API_KEY=... # OPENAI_BASE_URL=http://host.docker.internal:11434/v1/ # Ollama on host
One LLM key is enough — or none, if you point OPENAI_BASE_URL at a local Ollama instance. No API keys are required for fully local runs with Ollama plus a local embedding model like nomic-embed-text.
Step C — Start everything and open the app
cd ~/.khoj docker compose up -d # then open http://localhost:42110
Log in with your admin credentials, set the default chat model in server chat settings, and connect a client: the Obsidian community plugin, the Emacs package, desktop, or WhatsApp. Prefer pip? pipx install khoj, then USE_EMBEDDED_DB=true khoj --anonymous-mode.
Windows note
Install Docker Desktop with the Compose plugin, run the same three steps in PowerShell, and reach Ollama on the host via http://host.docker.internal:11434/v1/. For pip installs use py -m pip install khoj[local], with CUDA build flags on NVIDIA GPUs.
4. Real Use Cases That Justify the Hype
Khoj wins where your documents are the product and the answers must come from them — not from model weights. These are the patterns that survive contact with real vaults.
Second brain over Obsidian
Point the plugin at your self-hosted server and ask across the whole vault in plain language — semantic search finds the note you forgot, then the LLM answers from it. Your content never leaves your machine.
Scheduled research briefings
An agent with web search plus your reading list becomes a personal newsletter: daily news on your research topic, weekly project digests, Monday-morning briefings waiting in your inbox.
Org-mode copilot in Emacs
M-x khoj-chat and M-x khoj-search answer from org-roam without leaving the editor. For knowledge workers who live in plain text, this is the shortest path from question to cited answer.
Data questions with receipts
Agents with the Terrarium sandbox write and run Python to crunch numbers, then cite the docs and the code. Calculations stop being vibes and start being reproducible runs.
The pattern that works
Private corpus plus a clear question, repeated on a schedule. If you can name the folder of docs and the cadence of answers, Khoj probably automates it.
5. When NOT to Use Khoj
Honest section, because the fastest way to hate self-hosting is deploying five containers for a job a chat tab could do. Khoj costs ops attention — spend it where privacy and documents pay back.
⛔ Reach for something else when…
- • You only need casual chat with a local model — Open WebUI is simpler ops for a single chat box over Ollama.
- • You will not maintain Postgres, SearxNG, and three more containers — use the hosted cloud at app.khoj.dev or start with three PDFs somewhere lighter.
- • You plan to sell a modified Khoj as a service — AGPL-3.0 is copyleft: serve modified code over a network and you must share the source.
- • You expect cloud features on day one self-hosted — WhatsApp polish, newest automations, and computer control land on cloud first.
✅ Khoj is the right call when…
- • Your docs are the product: vaults, Notion, org-roam, PDFs you actually need cited answers from.
- • Privacy is non-negotiable — local Ollama plus local embeddings run the whole loop with zero data leaving your network.
- • You want research on a schedule, not a chat tab: briefings and digests that arrive without being asked.
- • You want agents with scoped knowledge and real tools — persona, files, web search, code execution — on your own hardware.
Golden rule
Prototype on the hosted cloud for a weekend, then decide: stay on cloud for convenience, or self-host when the vault gets sensitive enough to deserve its own server. Never pay for infrastructure before the questions prove their value.
Conclusion
Khoj earned its ~37k stars by solving an unglamorous problem well: letting you ask questions over a lifetime of notes and get answers with citations, from any client, with any model. The loop is simple — index, retrieve, reason, act — and the Docker quickstart genuinely runs in about half an hour.
My verdict: self-host it if your notes matter. Start with one vault and one cloud key, swap in Ollama once the habit sticks, and schedule one briefing that saves you a meeting a week. That is the compounding return a second brain is for.
Cheat Sheet
Install
- • docker compose up -d
- • port 42110
- • pipx install khoj
Configure
- • KHOJ_ADMIN_PASSWORD
- • one LLM key or Ollama
- • default chat model
Run
- • connect Obsidian / Emacs
- • build agents + automations
- • research with citations
