# Khoj: a self-hostable AI second brain for your docs and the web

> Khoj is an AGPL-3.0 Python application that indexes your files, answers from them and the web through any local or hosted LLM, and runs either on app.khoj.dev or from a docker-compose stack you own. The main judgement: useful if you want one search and chat surface over mixed personal documents, but the current release line is 2.0.0-beta, and the last push to master was on 2026-03-26.

**khoj-ai/khoj** — Your AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.

- Repository: https://github.com/khoj-ai/khoj
- Website: https://khoj.dev
- Stars: 37,525 · Forks: 2,498
- Language: Python
- License: AGPL-3.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/khoj-ai-khoj

## What problem Khoj is built to solve

Most people accumulate answers in places they never search again: a folder of Markdown notes, a few hundred PDFs, a Notion workspace, org-mode files if they live in Emacs. The tools that read those files and the tools that answer questions from them are usually different programs. Khoj's stated goal is to collapse that into one surface. The README describes it as "a personal AI app to extend your capabilities" that scales "from an on-device personal AI to a cloud-scale enterprise AI", and the feature list is explicit about what it ingests: image, pdf, markdown, org-mode, word and notion files.

The intended user is not a team building a RAG pipeline from scratch. It is someone who wants a working chat and semantic search interface over their own material without writing the retrieval layer. The README also lists non-text outputs (image generation, speech, playing messages) and access points beyond the browser: Obsidian, Emacs, desktop, phone and WhatsApp. That breadth is the product's actual pitch. It is a front end plus an indexer plus an agent runner, not a library you embed.

## How the pieces fit together in the repository

The docker-compose.yml is the clearest statement of the architecture, because it names the services Khoj expects to exist. There is a database service running docker.io/pgvector/pgvector:pg15, which tells you the vector store is Postgres with the pgvector extension rather than a dedicated vector database. There is a search service running docker.io/searxng/searxng:latest, which is how web answers are fetched without a commercial search API. There is a sandbox service running ghcr.io/khoj-ai/terrarium:latest with a health check against http://localhost:8080/health.

Then there is the server itself, which the compose file points at ghcr.io/khoj-ai/khoj:latest by default, with a commented-out build section for compiling from source. A separate computer service, ghcr.io/khoj-ai/khoj-computer:latest, exposes port 5900 and is gated behind a KHOJ_OPERATOR_ENABLED=True environment variable on the server, per the comment in the compose file. So the data flow is: documents get chunked and embedded, embeddings land in pgvector, a query goes through semantic search, and the retrieved context is handed to whichever LLM you configured. Web results arrive through the bundled SearXNG instance instead of an external search provider.

The Python side is visible in pyproject.toml: FastAPI and uvicorn for the HTTP layer, sentence-transformers and torch for embeddings, langchain-text-splitters for chunking, and the openai client library. That last dependency does not mean OpenAI is required. It means the OpenAI-compatible API shape is the common interface, which is how the README can claim support for llama3, qwen, gemma, mistral, gpt, claude, gemini and deepseek through one client path.

## Installing Khoj with Docker and running a first query

The README does not inline installation steps. It points to the self-hosting docs at docs.khoj.dev/get-started/setup, and the repository ships a docker-compose.yml that is the practical entry point. The compose file defaults the server to the published image, so the first command is a pull and start from the repository root.

```bash
docker compose up -d
```

That brings up Postgres with pgvector, SearXNG, the sandbox, the computer container and the Khoj server. The compose file defines a health check on the database (pg_isready -U postgres) and the server declares a depends_on condition of service_healthy, so the server waits for Postgres rather than racing it. If you would rather build from source, the file contains a commented build block with context: . that you uncomment, and the comment warns it "will take a few minutes".

The port mapping deserves attention before you start, because the compose file's own comment says that if you change the remote port (the right-hand side), you must also change the port in the args in the build section. Changing only the left-hand side requires nothing else.

```yaml
ports:
  # If changing the local port (left hand side), no other changes required.
  # If changing the remote port (right hand side),
  #   change the port in the args in the build section,
  #   as well
```

Once the stack is up, the workflow the README describes is: connect your documents, let Khoj index them, then ask questions. The README lists the supported inputs as "image, pdf, markdown, org-mode, word, notion files". For a first real use, point it at a small folder of Markdown rather than your entire archive, confirm that answers cite the files you expect, and only then widen the index. The FAQ in the README notes that you can also skip all of this and use the hosted app, which requires no setup.

## The beta release line is the real constraint

The most recent releases are 2.0.0-beta.28, 2.0.0-beta.27 and 2.0.0-beta.26, dated 2026-03-26, 2026-03-25 and 2026-03-25 respectively. Three beta tags in roughly a day is a fast cadence, and it means the version you install today is not a frozen artifact. The last push to master was on 2026-03-26, so the repository has not moved since that release burst. That is not the same as abandonment, but it does mean the project is not in a phase where you should expect a stable 2.0.0 tag to land on a schedule you can plan around.

There is a mismatch worth naming: pyproject.toml carries the classifier "Development Status :: 5 - Production/Stable" and the version line is generated by hatch-vcs from git tags. A classifier is a declaration, not a guarantee, and the tag history is the harder evidence. If your adoption decision depends on semantic versioning promises, the tag list is the thing to read, not the classifier.

A second constraint is the Python version range: requires-python is ">=3.10, <3.13". Python 3.13 is excluded. If your environment is pinned to 3.13 or newer, the package will refuse to install, and the Dockerfile sidesteps this by building on ubuntu:jammy with python3-pip rather than tracking the newest interpreter.

## Where Khoj is the wrong tool

Khoj is a full application, not a retrieval library. If you want to embed semantic search over your documents into an existing service, pulling in FastAPI, uvicorn, sentence-transformers, torch, a Postgres with pgvector, a SearXNG instance and a sandbox container is a lot of surface area for what might be a hundred lines of embedding code. The compose file makes the dependency count explicit, and each of those services is something you now run and upgrade.

The AGPL-3.0-or-later licence is the second reason to pause. pyproject.toml declares license = "AGPL-3.0-or-later" and the classifier confirms it. If you plan to offer a modified Khoj as a network service to third parties, the licence's network-use terms are the thing your legal team needs to read. This article cannot tell you what that means for your product; it can only tell you the licence identifier the project ships under.

Finally, the computer service is opt-in for a reason. It is gated behind KHOJ_OPERATOR_ENABLED=True and exposes port 5900, which is the VNC port. Enabling it gives Khoj a desktop to operate; it also gives anything that can reach that port a desktop. The compose file's comment marks it as disabled by default, and that default is worth keeping unless you specifically need the computer feature.

## How it differs from wiring up your own RAG stack

The obvious alternative is assembling the same pipeline yourself: a document loader, a splitter, an embedding model, pgvector or another store, and a chat interface. The difference is not capability, it is where the decisions live. In a hand-built stack you choose the chunker, the embedding model, the retrieval strategy and the prompt. In Khoj those are pinned in pyproject.toml: langchain-text-splitters == 0.3.11, sentence-transformers == 3.4.1, torch == 2.6.0, transformers >= 4.53.0. That pinning is a feature if you want a working system today and a constraint if you have opinions about chunk sizes or embedding models.

The second difference is the bundled web search. A hand-built stack usually reaches for a search API with a key and a bill. Khoj ships docker.io/searxng/searxng:latest in the compose file, so web answers come from an instance you run. That removes the API key and the per-query cost, and it adds a container you have to keep updated.

The third difference is the interface layer. Khoj ships clients for Obsidian, Emacs, desktop, phone and WhatsApp per the README. Reproducing that from a hand-built retrieval service means writing each client yourself. If you only ever query from one place, that advantage disappears.

## Licence and upgrade cost

The licence is AGPL-3.0-or-later, stated in both pyproject.toml and the classifier list. The practical implication for a self-hoster running Khoj privately is minimal: you are using the software, not distributing a modified version. The implication changes if you fork Khoj, modify it, and let other people interact with it over a network. The AGPL's network clause is the part to hand to counsel, and no article can substitute for that reading.

On upgrade cost, the repository gives you a version signal in versions.json and a lockfile in uv.lock, and the Docker path defaults to ghcr.io/khoj-ai/khoj:latest. Pinning to latest means every docker compose pull can move you across a beta boundary. The compose file also mentions ghcr.io/khoj-ai/khoj-cloud:latest for the prod image, which is a different artifact from the default. If you want reproducibility, the tag list (2.0.0-beta.28 and its predecessors) is where you pin, not latest.

The dependency set is heavy enough that image pulls and rebuilds are not instant. torch, transformers and sentence-transformers dominate the install, and the Dockerfile goes out of its way to avoid CUDA packages by setting CUDA_VISIBLE_DEVICES="" and pointing PIP_EXTRA_INDEX_URL at the CPU wheels for torch and llama-cpp-python. That is a deliberate trade: smaller image, no GPU acceleration in the default container.

## Conclusion

Adopt Khoj if you have a pile of Markdown, org-mode, PDF or Notion files and want one chat and semantic search surface over them, with the option to point it at a local model instead of a hosted one. Do not adopt it if you need a stable version number: the release line here is 2.0.0-beta.28 and the last push to master was on 2026-03-26, so you are tracking a beta branch. Before committing, verify two things yourself: that your document set fits the supported formats listed in the README, and that the port mapping in docker-compose.yml matches the port you actually expose, because changing the remote port requires a matching change in the build args.

## FAQ

### Is Khoj AI safe?

The repository is public and the licence is AGPL-3.0-or-later, so the code is auditable. If you self-host, your documents stay in the pgvector database you run; if you use app.khoj.dev, the README states no setup is required, which also means you are relying on the hosted service for data handling. The README does not document a security model for the optional computer service, which exposes port 5900 and is disabled unless KHOJ_OPERATOR_ENABLED=True is set.

### What is Khoj AI?

Khoj is described in the README as a personal AI app that scales from an on-device AI to a cloud-scale enterprise AI. It answers from the internet and from your documents, supports local and online LLMs, and can be reached from a browser, Obsidian, Emacs, desktop, phone or WhatsApp.

### Is the Khoj app free to use?

The README says Khoj is open-source and self-hostable, and that you can run it privately on your computer or try the cloud app at app.khoj.dev. The README does not state pricing for the hosted service; it only notes that no setup is required to use it.

## Sources

- [Official documentation](https://khoj.dev)
- [Official README](https://github.com/khoj-ai/khoj#readme)
- [Project repository](https://github.com/khoj-ai/khoj)
- [Release notes](https://github.com/khoj-ai/khoj/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/khoj-ai-khoj