Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Python 3.10, 3.11, or 3.12: Download Python
Git: Install Git
PostgreSQL with pgvector: Database and vector extension
Bun: Fast JavaScript runtime (Install Bun)
uv: Fast Python package manager (Install uv)

Optional Tools

Docker & Docker Compose: For containerized development
pre-commit: For automated code quality checks
Node.js/Yarn: Alternative to Bun for web development

Installation Methods

Using Pip (Recommended)
Using Docker

1. Clone and Setup Virtual Environment

# Clone the repository
git clone https://github.com/khoj-ai/khoj && cd khoj

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install Khoj with all extras
uv sync --all-extras

2. Install and Configure PostgreSQL

Khoj uses PostgreSQL with the pgvector extension for storing embeddings.

macOS
Windows
Linux

Install Postgres.app - comes pre-installed with pgvector.

# Create the database
createdb khoj -U postgres --password

Use the recommended installer
Follow pgvector installation instructions

# Create the database
createdb -U postgres khoj --password

Windows support for pgvector is experimental. Consider using Docker for a more reliable setup.

# Install PostgreSQL (Ubuntu/Debian)
sudo apt update
sudo apt install postgresql postgresql-contrib

# Install pgvector
sudo apt install postgresql-server-dev-all
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

# Create the database
sudo -u postgres createdb khoj --password

Set the POSTGRES_PASSWORD environment variable to match your database password. The default is postgres.

3. Build Frontend Assets

cd src/interface/web/

# Install dependencies and build
bun install
bun export

For frontend development, use bun dev to start a development server at http://localhost:3000. Always run bun export to test changes at http://localhost:42110 before creating a PR.

Streaming doesn’t work on the dev server (localhost:3000) due to Next.js SSR handling. Test streaming features on localhost:42110.

4. Run Khoj

Start the Server

khoj -vv

The server will start at http://localhost:42110

Configure Khoj

Access the web interface at http://localhost:42110
Add files and directories to index via the settings page
Click “Save” to trigger indexing

Wait for Indexing

Khoj will load ML models, generate embeddings, and index your content. This may take a few minutes on first run.

1. Install Docker

Make sure you have the latest versions of Docker and Docker Compose installed.

2. Clone and Configure

# Clone the repository
git clone https://github.com/khoj-ai/khoj && cd khoj

3. Update docker-compose.yml

Update environment variables as needed
Comment out the image line
Uncomment the build line in the server service

server:
  # image: ghcr.io/khoj-ai/khoj:latest
  build: .
  # ... rest of config

4. Run Khoj

# Start services (server + database)
docker-compose up -d

The server will be available at http://localhost:42110

5. Rebuild After Changes

# Rebuild without cache
docker-compose build --no-cache

# Restart services
docker-compose up -d

Development Setup Script

For a faster setup, use the provided development script:

# Basic setup (server + web app)
./scripts/dev_setup.sh

# Full setup (includes Desktop and Obsidian clients)
./scripts/dev_setup.sh --full

This script:

Installs the Khoj server and web app
Sets up Git hooks for automatic code formatting and type checking
Configures pre-commit hooks
Optionally installs Desktop and Obsidian client apps

Client Configuration

When testing with Khoj clients (Desktop, Obsidian, Emacs), update the server URL to point to your local instance:

http://127.0.0.1:42110

Validation and Testing

Before Making Changes

Install Git Hooks

./scripts/dev_setup.sh

If pre-commit isn’t installed:

pip install pre-commit
pre-commit install -t pre-push -t pre-commit

Verify Setup

# Run pre-commit checks manually
pre-commit run --hook-stage manual --all

Before Creating a PR

You must be in an active virtual environment to run tests and linters.

Create or Link GitHub Issue

Ensure there’s a GitHub issue that can be linked to your PR. Tag a maintainer on the issue for visibility. Discuss the code design before creating a PR to get it merged faster.

Run Tests

pytest

Run specific tests:

pytest tests/test_client.py
pytest tests/test_agents.py -v

Run Type Checker

mypy

Add Unit Tests

Think about how to verify your functionality with tests. Ask for help in the GitHub issue or Discord’s #contributors channel if you’re unsure.

After Creating a PR

Automated validation workflows will run for every PR. Tag a maintainer to trigger the workflows if they don’t start automatically. The workflows include:

Test Suite: Runs on Python 3.10, 3.11, and 3.12
Type Checking: Validates type hints with mypy
Linting: Checks code style with ruff
Pre-commit Hooks: Validates formatting and imports

Obsidian Plugin Development

Setup

Navigate to Plugin Directory

cd src/interface/obsidian

Install Dependencies

yarn install

Start Development Server

yarn dev

This continuously rebuilds the plugin as you make changes, outputting to main.js.

Loading in Obsidian

Install Khoj Plugin

Make sure you have the Khoj plugin installed in Obsidian.

Open Plugin Folder

Open Obsidian settings (gear icon)
Click ‘Community Plugins’
Click the folder icon next to ‘Installed Plugins’

Replace main.js

Navigate to the khoj folder and replace main.js with your development build from src/interface/obsidian/main.js.

Reload Obsidian

Restart Obsidian or use the “Reload app without saving” command to test your changes.

Windows Installation Troubleshooting

Command 'khoj' Not Recognized

Try reactivating the virtual environment:

.venv\Scripts\deactivate
.venv\Scripts\activate

If it still doesn’t work, repeat the installation process

Python Package Missing

Use uv to add the missing package:

uv add <package-name>

Then try running khoj again.

Command 'createdb' Not Recognized

Add PostgreSQL binaries to your PATH:

C:\Program Files\PostgreSQL\16\bin

Connection Refused Error

Locate pg_hba.conf in your PostgreSQL installation directory
Edit the file to use trust authentication:

host    all             postgres        127.0.0.1/32            trust
local   all             all                                     trust
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust

Restart PostgreSQL service

pgvector Installation Errors

Reinstall Visual Studio 2022 Build Tools with:
- Desktop development with C++ (in Workloads)
- MSVC C++ Build Tools (in Individual Components)
- Windows 10/11 SDK (in Individual Components)
- C++/CLI support for build tools (in Individual Components)
Open “x64 Native Tools Command Prompt for VS 2022” as Administrator
Follow pgvector Windows installation instructions

Environment Variables

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=khoj

# Server
KHOJ_DOMAIN=localhost
KHOJ_NO_HTTPS=true

# Debugging
KHOJ_DEBUG=true

Next Steps

Understand the Architecture

Learn about Khoj’s system design and code structure

Performance Guidelines

Learn about optimization and benchmarking

Find Issues to Work On

Browse beginner-friendly issues

Join Discord

Connect with other contributors

Development

​Prerequisites

​Installation Methods

​1. Clone and Setup Virtual Environment

​2. Install and Configure PostgreSQL

​3. Build Frontend Assets

​4. Run Khoj

​1. Install Docker

​2. Clone and Configure

​3. Update docker-compose.yml

​4. Run Khoj

​5. Rebuild After Changes

​Development Setup Script

​Client Configuration

​Validation and Testing

​Before Making Changes

​Before Creating a PR

​After Creating a PR

​Obsidian Plugin Development

​Setup

​Loading in Obsidian

​Windows Installation Troubleshooting

​Environment Variables

​Next Steps

Understand the Architecture

Performance Guidelines

Find Issues to Work On

Join Discord

Build docs developers (and LLMs) love

Prerequisites

Installation Methods

1. Clone and Setup Virtual Environment

2. Install and Configure PostgreSQL

3. Build Frontend Assets

4. Run Khoj

1. Install Docker

2. Clone and Configure

3. Update docker-compose.yml

4. Run Khoj

5. Rebuild After Changes

Development Setup Script

Client Configuration

Validation and Testing

Before Making Changes

Before Creating a PR

After Creating a PR

Obsidian Plugin Development

Setup

Loading in Obsidian

Windows Installation Troubleshooting

Environment Variables

Next Steps