Self-Hosting Khoj

Self-hosting Khoj gives you complete control over your data and AI infrastructure. Run it on your laptop, home server, or private cloud.

Why Self-Host?

Complete Privacy

Your data never leaves your network. Use Khoj entirely offline if needed.

Full Customization

Choose any AI model, customize features, and configure everything to your needs.

No Limits

Unlimited usage with no rate limits or subscription costs.

Local AI Models

Run completely offline with local models like Llama, Qwen, or Mistral.

First time self-hosting? Restart your Khoj server after the first run to ensure all settings are applied correctly.

Choose Your Installation Method

Docker (Recommended)
Pip Install

Docker provides the easiest setup with all dependencies included. Perfect for most users.

Prerequisites

MacOS

Install Docker Desktop or use Homebrew:Option 1: Docker DesktopDownload from Docker’s websiteOption 2: Homebrew

brew install --cask docker
brew install docker-compose

Windows

Install WSL2:

# Run in PowerShell as Administrator
wsl --install

Restart your machine
Install Docker Desktop with WSL2 backend (default)

All commands below should be run in your WSL2 terminal, not PowerShell or CMD.

Linux

Install Docker Engine and Docker Compose:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker.io docker-compose

# Fedora
sudo dnf install docker docker-compose

# Arch Linux
sudo pacman -S docker docker-compose

Or install Docker Desktop for Linux.

Installation Steps

Download Docker Compose File

mkdir ~/.khoj && cd ~/.khoj
wget https://raw.githubusercontent.com/khoj-ai/khoj/master/docker-compose.yml

Or download manually from GitHub

Configure Environment Variables

Open docker-compose.yml and set these essential variables:

docker-compose.yml

environment:
  # Required: Set secure admin credentials
  - [email protected]
  - KHOJ_ADMIN_PASSWORD=your-secure-password-here
  - KHOJ_DJANGO_SECRET_KEY=your-secret-key-here
  
  # Optional: Add API keys for online models
  - OPENAI_API_KEY=sk-...
  - ANTHROPIC_API_KEY=sk-ant-...
  - GEMINI_API_KEY=...
  
  # Optional: Use local models with Ollama
  # - OPENAI_BASE_URL=http://host.docker.internal:11434/v1/
  # - KHOJ_DEFAULT_CHAT_MODEL=qwen3

Generate a secure Django secret key using: python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

Start Khoj

cd ~/.khoj
docker-compose up

Wait for the message: 🌖 Khoj is ready to engage

First startup takes 2-5 minutes to download models and initialize the database.

Access Khoj

Open your browser and navigate to:

http://localhost:42110

Docker Architecture

The Docker setup includes multiple containers:

Container	Purpose	Port
server	Main Khoj application	42110
database	PostgreSQL with pgvector	5432
sandbox	Python code execution (Terrarium)	8080
search	SearxNG web search engine	8080
computer	Optional VNC desktop for automation	5900

Advanced Docker Configuration

Use Local Ollama Models

To use Ollama running on your host machine:

Start Ollama on your host: ollama serve
Uncomment these lines in docker-compose.yml:

- OPENAI_BASE_URL=http://host.docker.internal:11434/v1/
- KHOJ_DEFAULT_CHAT_MODEL=qwen3

Restart: docker-compose restart

See Ollama integration guide for details.

Enable Remote Access

To access Khoj from other devices on your network:

environment:
  - KHOJ_DOMAIN=192.168.1.100  # Your server's IP
  - KHOJ_NO_HTTPS=True          # Disable HTTPS for local network

Read the Remote Access guide for secure setup.

Disable Telemetry

Khoj collects anonymous usage data to improve the product. To opt out:

environment:
  - KHOJ_TELEMETRY_DISABLE=True

Install Khoj as a Python package. Gives you more control but requires manual dependency management.

Prerequisites

Python 3.10, 3.11, or 3.12
pip package manager
8GB RAM minimum (16GB recommended for local models)
5GB free disk space

Installation Steps

Install Khoj Package

MacOS
Windows
Linux

Apple Silicon (M1/M2/M3)
Intel Mac

CMAKE_ARGS="-DGGML_METAL=on" python -m pip install 'khoj[local]'

python -m pip install 'khoj[local]'

CPU
NVIDIA GPU
AMD GPU

py -m pip install 'khoj[local]'

$env:CMAKE_ARGS = "-DGGML_CUDA=on"
py -m pip install 'khoj[local]'

$env:CMAKE_ARGS = "-DGGML_HIPBLAS=on"
py -m pip install 'khoj[local]'

CPU
NVIDIA GPU
AMD GPU

python -m pip install 'khoj[local]'

CMAKE_ARGS="-DGGML_CUDA=on" FORCE_CMAKE=1 python -m pip install 'khoj[local]'

CMAKE_ARGS="-DGGML_HIPBLAS=on" FORCE_CMAKE=1 python -m pip install 'khoj[local]'

The [local] extra installs pgserver for a self-contained PostgreSQL database.

Start Khoj Server

USE_EMBEDDED_DB="true" khoj --anonymous-mode

--anonymous-mode disables authentication for single-user local setups. Remove it if you need login protection.

Initial Configuration

On first run, you’ll be prompted to:

Create admin account with email and password
Configure chat models with API keys:
- OpenAI API key
- Anthropic API key
- Gemini API key
- Or local model names like llama3, qwen3, mistral

Wait for: 🌖 Khoj is ready to engage

Access Khoj

Open your browser:

http://localhost:42110

Auto-Start on Boot

Windows Task Scheduler
MacOS/Linux (Cron)

Open Task Scheduler
Create Basic Task: “Start Khoj”
Trigger: “When the computer starts”
Action: “Start a program”
Program: py with arguments -m khoj --anonymous-mode

crontab -e

Add:

@reboot USE_EMBEDDED_DB="true" khoj --anonymous-mode

Configure Chat Models

After installation, configure which AI models to use.

Access Admin Panel

Navigate to: http://localhost:42110/server/admin
Login with your admin credentials

Use localhost, not 127.0.0.1, to avoid CSRF errors.

Add Chat Models

Create AI Model API Configuration

Go to AI Model API → Add AI Model API

OpenAI
Anthropic
Google Gemini
Local (Ollama)

Name: OpenAI
API Key: Your OpenAI API key
API Base URL: Leave empty (or set for proxy/Ollama)

Name: Anthropic
API Key: Your Anthropic API key
API Base URL: Leave empty

Name: Gemini
API Key: Your Gemini API key
API Base URL: Leave empty

Name: Ollama
API Key: ollama (any value works)
API Base URL: http://localhost:11434/v1/

Ensure Ollama is running: ollama serve

Create Chat Model

Go to Chat Model → Add Chat Model

OpenAI
Anthropic
Google Gemini
Local Model

Chat Model: gpt-4o or gpt-4o-mini
Model Type: OpenAI
AI Model API: Select your OpenAI config
Vision Enabled: ✓ (for image support)
Max Prompt Size: 128000 (optional)

Chat Model: claude-3-5-sonnet-20240620
Model Type: Anthropic
AI Model API: Select your Anthropic config

Chat Model: gemini-2.5-flash
Model Type: Google
AI Model API: Select your Gemini config

Chat Model: qwen3, llama3, etc.
Model Type: OpenAI
AI Model API: Select your Ollama config

Download models first: ollama pull qwen3

Set Default Models

Go to Server Chat Settings → Select your default models:

Default: Used for general chat
Advanced: Used for complex reasoning and research

Save changes.

Local Model Requirements

For offline AI models:

Component	Minimum	Recommended
RAM	8GB	16GB+
VRAM	-	8GB+ (GPU)
Storage	5GB	20GB+
CPU	4 cores	8+ cores

NVIDIA/AMD GPUs or Apple Silicon significantly speed up local model inference.

Sync Your Data

Connect your documents to Khoj:

Desktop App

Auto-sync local folders continuously

Obsidian Plugin

Sync your Obsidian vault seamlessly

Emacs Package

Native integration for Emacs users

Web Upload

Drag and drop files in the web interface

Configure Client Connection

Set your self-hosted server URL in client settings:

http://localhost:42110

Or your server’s IP for remote access:

http://192.168.1.100:42110

Upgrade Khoj

Docker
Pip

cd ~/.khoj
docker-compose down
docker-compose pull
docker-compose up

pip install --upgrade khoj

Troubleshooting

Dependency Conflicts (Pip)

Problem: Conflicting Python package versionsSolution: Use pipx or virtual environment

# Install pipx
python -m pip install pipx
python -m pipx ensurepath

# Install Khoj with pipx
pipx install khoj

Docker 'Killed' Error

Problem: Container exits with “Killed” messageSolution: Increase Docker memory limit

Docker Desktop: Settings → Resources → Memory → 4GB minimum

CSRF Error on Admin Panel

Problem: CSRF verification failedSolutions:

Use localhost instead of 127.0.0.1
Set KHOJ_DOMAIN in environment variables
Clear browser cookies and cache

Tokenizer Build Fails

Problem: Cannot build tokenizers packageSolution: Install Rust compiler

# MacOS
brew install rustup
rustup-init
source ~/.cargo/env

# Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Ollama Not Connecting

Problem: Cannot connect to local OllamaSolutions:

Ensure Ollama is running: ollama serve
Check URL is correct: http://localhost:11434/v1/
For Docker, use: http://host.docker.internal:11434/v1/

Uninstall

Docker
Pip

Remove all Khoj containers, volumes, and data:

cd ~/.khoj
docker-compose down --volumes
rm -rf ~/.khoj

# Uninstall package
pip uninstall khoj

# Remove database (if using embedded DB)
rm -rf ~/.khoj

# Or drop PostgreSQL database
dropdb khoj -U postgres

Next Steps

Remote Access

Access Khoj securely from anywhere

Use LiteLLM

Connect to 100+ AI models via proxy

Admin Panel

Advanced server configuration

Tailscale Setup

Secure private network access

Getting Help

Run into issues? We’re here to help:

Discord: discord.gg/BDgyabRM6e - Active community support
GitHub Issues: github.com/khoj-ai/khoj/issues
Documentation: Browse guides in the Advanced section

Get Started

Features

Clients

Data Sources

Advanced

Self-Hosting Khoj

Why Self-Host?

Complete Privacy

Full Customization

No Limits

Local AI Models

Choose Your Installation Method

Prerequisites

Installation Steps

Docker Architecture

Advanced Docker Configuration

Prerequisites

Installation Steps

Auto-Start on Boot

Configure Chat Models

Access Admin Panel

Add Chat Models

Local Model Requirements

Sync Your Data

Desktop App

Obsidian Plugin

Emacs Package

Web Upload

Configure Client Connection

Upgrade Khoj

Troubleshooting

Uninstall

Next Steps

Remote Access

Use LiteLLM

Admin Panel

Tailscale Setup

Getting Help

Build docs developers (and LLMs) love

Get Started

Features

Clients

Data Sources

Advanced

​Why Self-Host?

Complete Privacy

Full Customization

No Limits

Local AI Models

​Choose Your Installation Method

​Prerequisites

​Installation Steps

​Docker Architecture

​Advanced Docker Configuration

​Prerequisites

​Installation Steps

​Auto-Start on Boot

​Configure Chat Models

​Access Admin Panel

​Add Chat Models

​Local Model Requirements

​Sync Your Data

Desktop App

Obsidian Plugin

Emacs Package

Web Upload

​Configure Client Connection

​Upgrade Khoj

​Troubleshooting

​Uninstall

​Next Steps

Remote Access

Use LiteLLM

Admin Panel

Tailscale Setup

​Getting Help

Build docs developers (and LLMs) love

Why Self-Host?

Choose Your Installation Method

Prerequisites

Installation Steps

Docker Architecture

Advanced Docker Configuration

Prerequisites

Installation Steps

Auto-Start on Boot

Configure Chat Models

Access Admin Panel

Add Chat Models

Local Model Requirements

Sync Your Data

Configure Client Connection

Upgrade Khoj

Troubleshooting

Uninstall

Next Steps

Getting Help