This guide uses Docker Compose to run Khoj with the official docker-compose.yml from the Khoj repository. The official compose file includes all required services: Khoj server, PostgreSQL with pgvector, SearxNG for web search, and Terrarium for code execution.
| Requirement | Details |
|---|---|
| Operating System | Linux, macOS, Windows (with Docker Desktop or WSL2) |
| Docker | Docker Engine 20+ with Docker Compose plugin |
| RAM | 8 GB minimum (16 GB recommended for local models) |
| Disk Space | 5 GB minimum available |
| GPU | NVIDIA, AMD, or Mac M1+ (optional, speeds up local model inference) |
For Docker installation, see Docker.
mkdir -p ~/.khoj && cd ~/.khoj
wget https://raw.githubusercontent.com/khoj-ai/khoj/master/docker-compose.yml
Edit the docker-compose.yml file and set the required environment variables:
nano docker-compose.yml
In the server service section, update:
environment:
- KHOJ_ADMIN_PASSWORD=your-secure-admin-password
- KHOJ_DJANGO_SECRET_KEY=your-secret-key-min-50-characters-random
- POSTGRES_PASSWORD=your-secure-db-password
For Cloud Models:
- OPENAI_API_KEY=your_openai_api_key
- ANTHROPIC_API_KEY=your_anthropic_api_key
- GEMINI_API_KEY=your_gemini_api_key
For Local Models (Ollama):
- OPENAI_BASE_URL=http://host.docker.internal:11434/v1/
- KHOJ_DEFAULT_CHAT_MODEL=qwen3
For Remote Access:
- KHOJ_NO_HTTPS=True
- KHOJ_DOMAIN=192.168.0.104 # or khoj.example.com
- KHOJ_ALLOWED_DOMAIN=server # if using reverse proxy
For Web Search APIs:
- SERPER_DEV_API_KEY=your_serper_dev_api_key
- OLOSTEP_API_KEY=your_olostep_api_key
- FIRECRAWL_API_KEY=your_firecrawl_api_key
- EXA_API_KEY=your_exa_api_key
For Code Execution (Alternative to Terrarium):
- E2B_API_KEY=your_e2b_api_key
To Disable Telemetry:
- KHOJ_TELEMETRY_DISABLE=True
To Enable Khoj Computer Operator:
- KHOJ_OPERATOR_ENABLED=True
cd ~/.khoj
docker compose up -d
docker compose logs -f server
Success indicator: 🌖 Khoj is ready to engage appears in logs.
Open your browser to:
Create Admin Account:
Configure Chat Models:
localhost, not 127.0.0.1 (avoids CSRF errors)The official docker-compose.yml includes these services:
services:
database:
image: docker.io/pgvector/pgvector:pg15
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: postgres
volumes:
- khoj_db:/var/lib/postgresql/data/
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 30s
timeout: 10s
retries: 5
sandbox:
image: ghcr.io/khoj-ai/terrarium:latest
healthcheck:
test: ["CMD-SHELL", "curl -f http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 2
search:
image: docker.io/searxng/searxng:latest
volumes:
- khoj_search:/etc/searxng
environment:
- SEARXNG_BASE_URL=http://localhost:8080/
computer:
container_name: khoj-computer
image: ghcr.io/khoj-ai/khoj-computer:latest
ports:
- "5900:5900"
volumes:
- khoj_computer:/home/operator
server:
depends_on:
database:
condition: service_healthy
image: ghcr.io/khoj-ai/khoj:latest
ports:
- "42110:42110"
extra_hosts:
- "host.docker.internal:host-gateway"
working_dir: /app
volumes:
- khoj_config:/root/.khoj/
- khoj_models:/root/.cache/torch/sentence_transformers
- khoj_models:/root/.cache/huggingface
environment:
- POSTGRES_DB=postgres
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres
- POSTGRES_HOST=database
- POSTGRES_PORT=5432
- KHOJ_DJANGO_SECRET_KEY=secret
- KHOJ_DEBUG=False
- KHOJ_ADMIN_EMAIL=username@example.com
- KHOJ_ADMIN_PASSWORD=password
- KHOJ_TERRARIUM_URL=http://sandbox:8080
- KHOJ_SEARXNG_URL=http://search:8080
command: --host="0.0.0.0" --port=42110 -vv --anonymous-mode --non-interactive
volumes:
khoj_config:
khoj_db:
khoj_models:
khoj_search:
khoj_computer:
┌─────────────────────────────────────────────────────────┐
│ Docker Network │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Khoj │───▶│ PostgreSQL │ │ SearxNG │ │
│ │ Server │ │ + pgvector │ │ (Search) │ │
│ │ (Port 42110)│ └──────────────┘ └────────────┘ │
│ └──────┬───────┘ ▲ │
│ │ │ │
│ ▼ │ │
│ ┌──────────────┐ ┌─────┴──────┐ ┌────────────┐ │
│ │ Terrarium │ │ Volumes │ │ Khoj │ │
│ │ (Sandbox) │ │ (Persist) │ │ Computer │ │
│ └──────────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────┘
│
▼
┌──────────────┐
│ Browser │
│ localhost: │
│ 42110 │
└──────────────┘
| Service | Image | Purpose |
|---|---|---|
| server | ghcr.io/khoj-ai/khoj:latest |
Main Khoj application |
| database | pgvector/pgvector:pg15 |
PostgreSQL with vector search |
| sandbox | ghcr.io/khoj-ai/terrarium:latest |
Python code execution sandbox |
| search | searxng/searxng:latest |
Privacy-respecting web search |
| computer | ghcr.io/khoj-ai/khoj-computer:latest |
Computer operator (optional) |
| Volume | Purpose |
|---|---|
khoj_config |
Configuration files and settings |
khoj_db |
PostgreSQL database (persistent) |
khoj_models |
Cached ML models (can re-download) |
khoj_search |
SearxNG configuration |
khoj_computer |
Computer operator data |
cd ~/.khoj
docker compose pull
docker compose up -d
# Backup all volumes
tar -czf khoj-backup-$(date +%Y%m%d).tar.gz ~/.khoj
# Backup database only
docker compose exec database pg_dump -U postgres postgres > khoj-db-backup.sql
| Issue | Solution |
|---|---|
| Container won’t start | Check logs: docker compose logs server |
| CSRF error | Use localhost, not 127.0.0.1 |
| Database connection failed | Ensure database service is healthy |
| Out of memory | Increase Docker RAM allocation |
| Can’t access remotely | Set KHOJ_DOMAIN and KHOJ_NO_HTTPS=True |
| Models not loading | Check volume mounts for khoj_models |
Any questions?
Feel free to contact us. Find all contact information on our contact page.