# Project pack: Khoj @ ae229ca

Facts about **Khoj** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Khoj is an AI assistant that reads your own notes and files (PDFs, Word, Markdown, Obsidian, Notion) and answers questions about them, alongside fresh results from the web. You can make custom helpers with their own personality, schedule regular research emails, and reach it from the browser, Obsidian, Emacs, the desktop or your phone. It works with local models through Ollama or with cloud models such as ChatGPT, Claude and Gemini.

## Version and source
- Repository: https://github.com/khoj-ai/khoj
- Pinned commit: `ae229ca894c0b80ad84664afcfdde523b5e87057`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/khoj-ai/khoj/archive/ae229ca894c0b80ad84664afcfdde523b5e87057.zip
- Official docs: https://docs.khoj.dev
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just your own household), you must offer them your source code under the same licence. Private use has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/khoj-ai/khoj bespoke-khoj
  cd bespoke-khoj
  git checkout --detach ae229ca894c0b80ad84664afcfdde523b5e87057
  # Prepare development requirements and local configuration first.
  # Setup notes: needs a local Postgres with pgvector; see documentation/docs/contributing/development.mdx
  uv sync --all-extras && (cd src/interface/web && bun install && bun export) && khoj -vv --anonymous-mode
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  mkdir ~/.khoj && cd ~/.khoj
  wget https://raw.githubusercontent.com/khoj-ai/khoj/ae229ca894c0b80ad84664afcfdde523b5e87057/docker-compose.yml
  # edit docker-compose.yml: set KHOJ_ADMIN_PASSWORD and KHOJ_DJANGO_SECRET_KEY, and an AI key (or OPENAI_BASE_URL for Ollama)
  docker compose up
  # wait for "Khoj is ready to engage", then open http://localhost:42110 (admin panel at /server/admin)
  ```

- Needs: Docker with Docker Compose (on Windows, WSL2), 8 GB RAM or more is comfortable; a GPU helps for local models, For development, Python 3.10–3.12 with uv, Postgres with pgvector, and bun for the web app
- Develop: `uv sync --all-extras && (cd src/interface/web && bun install && bun export) && khoj -vv --anonymous-mode   # needs a local Postgres with pgvector; see documentation/docs/contributing/development.mdx`
- Test: `pytest`
- Check/lint: `mypy`
- Stack: python, typescript (Django, FastAPI, Next.js, React, Tailwind CSS, sentence-transformers). Difficulty for a non-developer with an AI: **advanced**. A Python (Django + FastAPI) server with a Next.js web app, plus Obsidian, Emacs, desktop and Android clients in the same repo. Models, agents and search providers are set in the admin panel or compose file. Code changes need Python 3.10–3.12, Postgres with pgvector, uv and bun, and the web app must be exported into the server before testing.

## Customisation points (settings → extend → code)
- **chat-models** [settings]: Which models people can choose and which one is the default. Add Ollama, OpenAI, Claude or Gemini. → `Admin panel → Chat Model Options and Server Chat Settings (http://localhost:42110/server/admin; documentation/docs/advanced/admin.md)`
- **agents** [settings]: Helpers with their own personality, model, files and tools, e.g. "Garden Planner" or "Recipe Coach". → `Agents page in the web app, or Admin panel → Agents (documentation/docs/features/agents.md)`
- **data-sources** [settings]: Choose which notes and documents Khoj can read. → `Settings page (upload files, Notion, GitHub); Obsidian, Emacs and Desktop clients sync folders (documentation/docs/data-sources/)`
- **compose-env** [settings]: Local or cloud models, web search, code sandbox, remote access and telemetry. → `docker-compose.yml environment (KHOJ_* variables, provider keys, web search providers, telemetry)`
- **login** [settings]: Turn on real logins so several people, or several devices over the internet, can use it safely. → `Remove --anonymous-mode in docker-compose.yml; magic links or Google login (documentation/docs/advanced/authentication.mdx)`
- **automations** [extend]: Scheduled research or reminders delivered by email. → `Automations page; needs Resend and authentication when self-hosting (documentation/docs/features/automations.md)`
- **api-and-clients** [extend]: Push notes from other apps, or ask Khoj from scripts and shortcuts. → `REST API in src/khoj/routers/ (api_chat.py, api_content.py); clients in src/interface/ (obsidian, emacs, desktop, android)`
- **prompts** [code]: The built-in instructions Khoj gives the model, e.g. tone, length or language of answers. → `src/khoj/processor/conversation/prompts.py`
- **web-app** [code]: New views or a different look. Run bun export so the server serves your changes. → `src/interface/web/app/** (chat, agents, automations, settings, search), styles in src/interface/web/app/globals.css`
- **content-types** [code]: Teach Khoj to read a new kind of file. → `src/khoj/processor/content/** (pdf, docx, markdown, org_mode, notion, github, images)`

## Must keep working
- Each user's notes, chats and agents stay private to them once logins are on.
- The database volume (khoj_db). Back it up before upgrades; schema changes need a Django migration in src/khoj/database/migrations/.
- Sync from the Obsidian, Emacs and desktop clients. Don't change existing API routes they rely on.
- Run bun export after web app changes, or the server keeps serving the old pages.

## Staying updatable
Models, agents, data sources and automations are all settings, so most households never need a fork. Upstream asks contributors to discuss changes in a linked GitHub issue or on Discord before opening a pull request. Development has slowed in 2026 while the team works on a new product (Pipali), so expect fewer updates.

## Data, costs and safety
- Personal data: **yes**. Stored in: Notes, document text, embeddings, chats, agents and automations in PostgreSQL with pgvector (khoj_db volume). Downloaded search models in khoj_models; settings in khoj_config. Your notes and chats are among the most personal data you have. Back up the khoj_db volume (pg_dump) and keep your original files elsewhere. Khoj stores a copy of the text of synced files, not your only copy.
- Service: Chat model provider (OpenAI, Anthropic, Google Gemini, or any OpenAI-compatible API) (optional, pay-per-use with your own key): The AI that writes answers. One provider, cloud or local, is needed.
- Service: Ollama, LM Studio or vLLM (optional, free (uses your own computer)): Run the chat model privately on your own hardware via OPENAI_BASE_URL.
- Service: SearXNG (bundled in docker-compose) (optional, free, self-hosted): Private web search for online answers. Paid alternatives (Serper, Exa, Firecrawl, Olostep) are optional.
- Service: Terrarium sandbox (bundled) or E2B (optional, free (Terrarium) or pay-per-use (E2B)): Runs Python code the AI writes, e.g. for charts and calculations.
- Service: Resend (email) (optional, free tier available): Magic-link logins and automation emails. Needed for scheduled automations when self-hosting.
- Service: PostHog telemetry (optional, free): Anonymous usage counts sent to Khoj. Turn off with KHOJ_TELEMETRY_DISABLE=True.
- Setting `KHOJ_ADMIN_EMAIL`: Email for the admin account that opens the admin panel.
- Setting `KHOJ_ADMIN_PASSWORD` (**secret**: the person enters it themselves, never in chat): Admin password. Change it from the default in docker-compose.yml.
- Setting `KHOJ_DJANGO_SECRET_KEY` (**secret**: the person enters it themselves, never in chat): Long random string that protects logins. Change it from "secret".
- Setting `OPENAI_API_KEY` (**secret**: the person enters it themselves, never in chat): OpenAI key, or any key your OpenAI-compatible server needs.
- Setting `OPENAI_BASE_URL`: Point at Ollama or another OpenAI-compatible server, e.g. http://host.docker.internal:11434/v1/.
- Setting `KHOJ_DEFAULT_CHAT_MODEL`: Model name to use by default, e.g. qwen3 with Ollama.
- Setting `ANTHROPIC_API_KEY` (**secret**: the person enters it themselves, never in chat): Anthropic (Claude) key.
- Setting `GEMINI_API_KEY` (**secret**: the person enters it themselves, never in chat): Google Gemini key.
- Setting `KHOJ_SEARXNG_URL`: Address of the SearXNG used for web search (the bundled one by default).
- Setting `KHOJ_DOMAIN`: The address you'll reach Khoj at from other devices (no http prefix). Needed for remote access.
- Setting `KHOJ_NO_HTTPS`: Set True only when serving over plain HTTP on a trusted home network.
- Setting `KHOJ_TELEMETRY_DISABLE`: Set True to stop anonymous usage telemetry.
- Setting `RESEND_API_KEY` (**secret**: the person enters it themselves, never in chat): Resend key for magic-link logins and automation emails.
- Setting `POSTGRES_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password (postgres by default in the compose file; change it if the database is reachable from elsewhere).
- The default docker-compose runs in anonymous mode with no login. Keep it on your own computer, or remove --anonymous-mode and set up logins before other people or the internet can reach it.
- Change KHOJ_ADMIN_PASSWORD, KHOJ_DJANGO_SECRET_KEY and the Postgres password from the defaults in the compose file before first start.
- When you chat with a cloud model, relevant snippets of your notes are sent to that provider. Use Ollama or another local model to keep everything at home.
- The default compose file also starts a "computer" container (a desktop the AI can control when KHOJ_OPERATOR_ENABLED is on) and publishes its VNC port 5900. Delete that service if you don't need it, and never expose port 5900 to the internet.
- The compose file uses :latest images, so the version you run may be newer than the pinned commit. Pin image tags for predictable updates.

---

# Customising Khoj

Khoj has a Python server (Django for data and the admin panel, FastAPI routers for the API) and a Next.js web app that is exported into the server. **Models, agents, data sources and automations are all settings.** Exhaust levels 1 and 2 before touching code.

## Level 1: Settings (no code)
- **Compose file:** set `KHOJ_ADMIN_EMAIL`, `KHOJ_ADMIN_PASSWORD`, `KHOJ_DJANGO_SECRET_KEY` and the Postgres password before the first start. Add a provider key (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`) or uncomment `OPENAI_BASE_URL` and `KHOJ_DEFAULT_CHAT_MODEL` for Ollama. `KHOJ_TELEMETRY_DISABLE=True` turns off telemetry.
- **Admin panel** (`http://localhost:42110/server/admin`): *Chat Model Options* (the models people can pick), *Server Chat Settings* (the default model), *Agents*, search and speech models.
- **Agents:** the Agents page in the web app creates helpers with a personality, chat model, files and tools.
- **Your data:** upload files on the Settings page, connect Notion or GitHub, or install the Obsidian, Emacs or Desktop client to sync a folder.
- **Logins:** remove `--anonymous-mode` from the compose `command` and set up magic links (Resend) or Google login.
- **Remote access:** `KHOJ_DOMAIN` (and `KHOJ_NO_HTTPS=True` only on a trusted home network).

## Level 2: Extend (no fork)
- **Automations:** scheduled research sent by email. Self-hosted, this needs Resend and logins switched on.
- **Web search:** the bundled SearXNG works out of the box; Serper, Exa, Firecrawl or Olostep keys add paid options.
- **Code sandbox:** the bundled Terrarium container, or `E2B_API_KEY` for a hosted one.
- **API and clients:** the server's REST API (`src/khoj/routers/`) is what the Obsidian, Emacs, Desktop and Android clients use. Scripts can push notes or ask questions the same way.
- **WhatsApp:** documented in `documentation/docs/clients/whatsapp.md`.

## Level 3: Code

| Change | Where |
|---|---|
| Model instructions and tone | `src/khoj/processor/conversation/prompts.py` |
| Chat, agents, automations, settings screens | `src/interface/web/app/**` (then `bun export`) |
| Styles | `src/interface/web/app/globals.css` |
| API endpoints | `src/khoj/routers/*.py` |
| Data | `src/khoj/database/models/__init__.py` + a migration in `src/khoj/database/migrations/` |
| New file type | `src/khoj/processor/content/<type>/` |
| Search filters (dates, files, words) | `src/khoj/search_filter/` |

## Running locally
- **Just use it:** download the compose file pinned to the commit, edit the passwords and model settings, run `docker compose up`, and open http://localhost:42110 once the log says "Khoj is ready to engage". Restart once after the first run.
- **Develop:**
  1. Install Postgres with pgvector and create a `khoj` database.
  2. Run `uv sync --all-extras` (Python 3.10–3.12).
  3. In `src/interface/web`, run `bun install && bun export`.
  4. Start with `khoj -vv` (add `--anonymous-mode` for a single user).
  5. Or run `./scripts/dev_setup.sh`, which also installs the git hooks.
- **Check:** `pytest` and `mypy`, or `pre-commit run --hook-stage manual --all`.

## Pitfalls
- `bun dev` (port 3000) doesn't stream chat replies. Always test through `bun export` on port 42110.
- The default compose uses `:latest` images. Pin tags if you want updates only when you choose.
- From inside Docker, Ollama on your own computer is `http://host.docker.internal:11434/v1/`.
- Back up the `khoj_db` volume before upgrades. Models in `khoj_models` can be re-downloaded.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/khoj/ae229ca/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/khoj/ae229ca/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/khoj/ae229ca/r2/SKILL.md)