Khoj ist ein Open-Source-KI-Assistent, der als „AI Second Brain" deine persönlichen Dokumente – PDFs, Markdown-Dateien, Word-Dateien, Notion-Seiten oder Org-Mode-Dateien – indiziert und per natürlichsprachlichem Chat durchsuchbar macht. Mit über 35.000 GitHub-Stars und Lizenz AGPL-3.0 ist er eines der aktivsten Selbsthosting-KI-Projekte überhaupt. Wer seine Daten nicht in die Cloud geben möchte, bekommt hier einen vollständig lokal betreibbaren Assistenten, der optional mit Ollama-Modellen (Llama3, Qwen, Gemma, Mistral) arbeitet – ohne externen API-Schlüssel. Diese Anleitung zeigt den plattformneutralen Weg per Docker Compose, der auf jedem Linux-Server, jeder VM oder einem NAS mit Docker-Unterstützung funktioniert.

Voraussetzungen

Docker Engine >= 20.10 und Docker Compose Plugin v2 auf dem Host installiert – falls noch nicht vorhanden, hilft die Anleitung Docker und Docker Compose auf Linux installieren.
Mindestens 8 GB RAM (16 GB empfohlen, wenn lokale LLMs über Ollama laufen sollen); Sentence-Transformer-Modelle brauchen allein mehrere Gigabyte.
Mindestens 10 GB freier Festplattenspeicher – 5+ GB für ML-Modell-Cache, Rest für Datenbank und Konfiguration.
Internetzugang beim ersten Start (Image-Pull und Modell-Download); danach ist Offline-Betrieb möglich.
Optional: Ollama auf dem Host für vollständig lokale LLM-Inferenz ohne Cloud-API-Kosten (ollama.com).
Optional: Reverse Proxy mit SSL für öffentlichen Zugriff – z. B. per Traefik als Docker-Reverse-Proxy.
Texteditor sowie curl für Verifikationsschritte.

Eckdaten im Überblick

Eigenschaft	Wert
Haupt-Image	`ghcr.io/khoj-ai/khoj:latest` (GitHub Container Registry, nicht Docker Hub)
Datenbank-Image	`docker.io/pgvector/pgvector:pg15` (PostgreSQL + pgvector, Pflicht)
Weitere Services	`ghcr.io/khoj-ai/terrarium:latest`, `docker.io/searxng/searxng:latest`
Web-UI / API Port	`42110:42110`
Admin-Panel	`http://localhost:42110/server/admin`
Lizenz	AGPL-3.0
Plattformen	amd64, arm64 (Apple M-Series, ARM-NAS)
RAM minimum	8 GB (16 GB mit lokalen LLMs empfohlen)

Volume	Zweck
`khoj_config`	Khoj-Konfigurationsdaten (`/root/.khoj/`)
`khoj_db`	PostgreSQL-Datenbankdaten (`/var/lib/postgresql/data/`)
`khoj_models`	Sentence-Transformer- und Hugging-Face-Modell-Cache (doppelt gemountet, kein Fehler)
`khoj_search`	SearxNG-Konfiguration (`/etc/searxng`)

Schritt 1: Projektordner anlegen

Lege einen dedizierten Ordner für den Khoj-Stack an. Alle Konfigurationsdateien landen hier; die eigentlichen Daten speichert Docker in benannten Volumes.

mkdir -p /opt/khoj
cd /opt/khoj

Wer keinen Root-Zugriff hat oder einen Heimserver nutzt, kann auch ~/khoj wählen – der Rest der Anleitung funktioniert identisch.

Verifizieren: ls /opt/khoj gibt einen leeren Ordner zurück (noch keine Dateien, das ist korrekt).

Schritt 2: .env-Datei mit sicheren Werten anlegen

Die .env-Datei enthält alle sicherheitskritischen Werte. Die drei mit :? markierten Variablen sind im compose-File als Pflichtfelder deklariert – fehlen sie, verweigert Docker den Start. Besonders wichtig: Der Standardwert secret für den Django-Secret-Key und password für das Admin-Passwort aus dem offiziellen Beispiel sind unter keinen Umständen produktiv zu verwenden.

Einen sicheren Secret-Key erzeugst du so:

python3 -c "import secrets; print(secrets.token_urlsafe(50))"
# Alternativ:
openssl rand -base64 50

Lege nun die .env-Datei an (Werte anpassen):

# /opt/khoj/.env

# --- Pflichtfelder ---
KHOJ_DJANGO_SECRET_KEY=hier-deinen-langen-zufaelligen-schluessel-eintragen
KHOJ_ADMIN_EMAIL=admin@example.com
KHOJ_ADMIN_PASSWORD=sicheres-admin-passwort

# --- Datenbank ---
POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=sicheres-db-passwort

# --- Optionale Cloud-APIs (auskommentiert lassen fuer Offline-Betrieb) ---
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=...
# GEMINI_API_KEY=...

# --- Lokale LLMs via Ollama auf dem Host (auskommentieren zum Aktivieren) ---
# OPENAI_BASE_URL=http://host.docker.internal:11434/v1/

# --- Oeffentlicher Zugriff via Reverse Proxy (optional) ---
# KHOJ_DOMAIN=khoj.deine-domain.de
# KHOJ_NO_HTTPS=True

Verifizieren: cat /opt/khoj/.env zeigt alle Variablen. Stelle sicher, dass keine Standardwerte wie secret oder password mehr enthalten sind. Die Datei sollte nur für den eigenen Benutzer lesbar sein: chmod 600 /opt/khoj/.env.

Schritt 3: compose.yaml anlegen

Das folgende compose-File entspricht der offiziellen Khoj-Konfiguration. Beachte die zwei wichtigen Punkte: Erstens nutzt die Datenbank das spezialisierte pgvector/pgvector:pg15-Image (Standard-PostgreSQL würde beim Start an der fehlenden Erweiterung scheitern). Zweitens enthält der Server-Service extra_hosts: host.docker.internal:host-gateway – das ist notwendig, damit Khoj im Container Ollama auf dem Host via host.docker.internal erreichen kann.

# /opt/khoj/compose.yaml
services:
  database:
    image: docker.io/pgvector/pgvector:pg15
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set}
      POSTGRES_DB: ${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
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 2

  search:
    image: docker.io/searxng/searxng:latest
    restart: unless-stopped
    volumes:
      - khoj_search:/etc/searxng
    environment:
      - SEARXNG_BASE_URL=http://localhost:8080/

  server:
    image: ghcr.io/khoj-ai/khoj:latest
    restart: unless-stopped
    depends_on:
      database:
        condition: service_healthy
    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_DB:-postgres}
      - POSTGRES_USER=${POSTGRES_USER:-postgres}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set}
      - POSTGRES_HOST=database
      - POSTGRES_PORT=5432
      - KHOJ_DJANGO_SECRET_KEY=${KHOJ_DJANGO_SECRET_KEY:?KHOJ_DJANGO_SECRET_KEY must be set}
      - KHOJ_DEBUG=False
      - KHOJ_ADMIN_EMAIL=${KHOJ_ADMIN_EMAIL:?KHOJ_ADMIN_EMAIL must be set}
      - KHOJ_ADMIN_PASSWORD=${KHOJ_ADMIN_PASSWORD:?KHOJ_ADMIN_PASSWORD must be set}
      - KHOJ_TERRARIUM_URL=http://sandbox:8080
      - KHOJ_SEARXNG_URL=http://search:8080
      # Lokale LLMs via Ollama auf dem Host:
      # - OPENAI_BASE_URL=${OPENAI_BASE_URL}
      # Cloud-APIs (optional):
      # - OPENAI_API_KEY=${OPENAI_API_KEY}
      # - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # - GEMINI_API_KEY=${GEMINI_API_KEY}
      # Oeffentlicher Zugriff:
      # - KHOJ_DOMAIN=${KHOJ_DOMAIN}
      # - KHOJ_NO_HTTPS=True
    command: --host="0.0.0.0" --port=42110 -vv --anonymous-mode --non-interactive

volumes:
  khoj_config:
  khoj_db:
  khoj_models:
  khoj_search:

Verifizieren: Prüfe die YAML-Syntax mit docker compose -f /opt/khoj/compose.yaml config. Der Befehl gibt die aufgelöste Konfiguration aus; bei Syntaxfehlern erscheint eine Fehlermeldung mit Zeilennummer.

Schritt 4: Stack starten

Starte alle vier Container im Hintergrund. Beim ersten Aufruf werden die Images von ghcr.io und Docker Hub heruntergeladen – das dauert je nach Internetverbindung einige Minuten.

cd /opt/khoj
docker compose up -d

Beim ersten Start lädt Khoj außerdem Sentence-Transformer-Modelle (~500 MB oder mehr) in das Volume khoj_models. Der server-Container startet erst, wenn database den Healthcheck besteht (condition: service_healthy).

Verifizieren:

docker compose ps

Erwartete Ausgabe (alle Services running oder Up, database nach einigen Sekunden auch healthy):

NAME              IMAGE                              STATUS
khoj-database-1   pgvector/pgvector:pg15             Up (healthy)
khoj-sandbox-1    ghcr.io/khoj-ai/terrarium:latest   Up
khoj-search-1     searxng/searxng:latest             Up
khoj-server-1     ghcr.io/khoj-ai/khoj:latest        Up

Prüfe zusätzlich die Erreichbarkeit der Web-UI:

curl -I http://localhost:42110

Erwartete Antwort: HTTP/1.1 200 OK oder 302 Found. Falls der Server noch startet: kurz warten und wiederholen. Logs bei Problemen: docker compose logs -f server.

Schritt 5: Erste Einrichtung im Browser

Öffne http://localhost:42110 im Browser. Im Standardmodus (--anonymous-mode) ist kein Login erforderlich – du landest direkt im Chat-Interface. Das ist für den Einzelbenutzer auf einem lokalen Server praktisch; für Mehrbenutzerbetrieb oder öffentlichen Zugriff muss dieser Modus deaktiviert werden (dazu mehr im FAQ-Abschnitt).

Das Admin-Panel erreichst du unter http://localhost:42110/server/admin mit den in der .env gesetzten Zugangsdaten. Hier verwaltest du KI-Modelle, Benutzer und Indexierungsquellen.

Dokumente lädst du über das Menü „Files" oder „Sync" hoch. Unterstützte Formate: PDF, Markdown, Word (.docx), Notion-Seiten (über Plugin), Org-Mode-Dateien. Für automatische Synchronisation mit Obsidian oder Emacs gibt es offizielle Plugins.

Verifizieren: Das Chat-Interface lädt und zeigt eine Eingabemaske. Eine Testnachricht wie „Hallo" sollte eine Antwort erzeugen (anfangs ohne hochgeladene Dokumente eine generische KI-Antwort). Im Admin-Panel unter /server/admin ist der Login mit den gesetzten Zugangsdaten erfolgreich.

Schritt 6: Lokale LLMs mit Ollama einrichten (optional)

Wer vollständig offline und ohne Cloud-API-Kosten arbeiten möchte, kann Ollama auf dem Host-System installieren und Khoj darauf zeigen lassen. Die Kombination von Ollama und lokalen LLMs ist dabei ein bewährter Ansatz im Self-Hosting-Bereich.

Ollama auf dem Host starten und ein Modell laden:

# Ollama installieren (Linux):
curl -fsSL https://ollama.com/install.sh | sh

# Ein Modell herunterladen (Beispiel: Llama 3.1 8B, ~4.7 GB):
ollama pull llama3.1

Kommentiere in der .env die Ollama-Zeile ein:

OPENAI_BASE_URL=http://host.docker.internal:11434/v1/

Und in der compose.yaml die entsprechende Zeile unter environment im server-Service:

      - OPENAI_BASE_URL=${OPENAI_BASE_URL}

Stack neu starten:

docker compose up -d

Jetzt muss das Modell noch im Admin-Panel registriert werden. Öffne http://localhost:42110/server/admin, navigiere zu „AI Model API" und lege einen neuen Eintrag an: Name ollama, API Base URL http://host.docker.internal:11434/v1/. Danach unter „Chat Models" ein neues Modell anlegen: Typ openai, Name = genau der Ollama-Modellname (z. B. llama3.1).

Verifizieren: Im Chat-Interface kannst du das neue Modell auswählen. Eine Testnachricht sollte eine Antwort vom lokalen Llama-Modell liefern. Im Terminal: docker compose logs -f server sollte keine Verbindungsfehler zu host.docker.internal:11434 zeigen.

Schritt 7: Updates und Backup

Da alle persistenten Daten in benannten Docker-Volumes liegen, ist das Update-Verfahren einfach und sicher:

cd /opt/khoj
docker compose pull
docker compose up -d

Für Backups der Volumes empfiehlt sich ein Skript, das die Volumes temporär exportiert. Eine systematische Backup-Strategie findest du in der Anleitung 3-2-1-Backup-Strategie umsetzen. Das wichtigste Volume ist khoj_db (PostgreSQL-Daten) – es enthält alle Indizes und Embeddings.

# Datenbank-Volume sichern (Beispiel):
docker run --rm \
  -v khoj_db:/data \
  -v /backup:/backup \
  alpine tar czf /backup/khoj_db_$(date +%Y%m%d).tar.gz -C /data .

Zum Stoppen des Stacks ohne Datenverlust:

docker compose down

Verifizieren: Nach dem Update zeigt docker compose ps wieder alle Services als Up. Mit docker compose logs server | grep -i version kannst du die aktuell laufende Khoj-Version im Log ablesen.

Troubleshooting / Typische Fehler

„POSTGRES_PASSWORD must be set" / Start schlägt fehl: Die :?-Syntax in der compose.yaml erzwingt gesetzte Variablen. Ursache: .env-Datei fehlt, liegt im falschen Verzeichnis oder der Variablenname enthält einen Tippfehler. Fix: Im Projektordner (/opt/khoj/) prüfen, ob .env vorhanden ist und alle drei Pflichtfelder enthält.
Server startet nicht, obwohl Datenbank läuft: Der server-Service wartet auf den Healthcheck der Datenbank (condition: service_healthy). Auf langsamen Systemen kann der Standard-Healthcheck-Timeout von 5 Versuchen à 30 s überschritten werden. Fix: In der compose.yaml unter database.healthcheck den Wert retries auf 10 erhöhen und start_period: 60s ergänzen.
Ollama nicht erreichbar (Verbindungsfehler im Log): Ursache fast immer: localhost statt host.docker.internal in OPENAI_BASE_URL. Im Container verweist localhost auf den Container selbst, nicht auf den Host. Fix: OPENAI_BASE_URL=http://host.docker.internal:11434/v1/ – die extra_hosts-Konfiguration im compose-File löst diesen Hostnamen korrekt auf.
Port 42110 belegt („bind: address already in use"): Ein anderer Dienst nutzt diesen Port. Fix: In der compose.yaml den linken Port ändern, z. B. 4211:42110 (Host-Port 4211, Container-Port bleibt 42110).
Falsches Image: „docker pull khoj/khoj" schlägt fehl oder zieht ein veraltetes Image: Khoj liegt ausschließlich auf der GitHub Container Registry. Das korrekte Image ist ghcr.io/khoj-ai/khoj:latest, nicht docker.io/khoj/khoj.
Fehlermeldung „extension pgvector does not exist": Du verwendest das Standard-PostgreSQL-Image statt pgvector/pgvector:pg15. Fix: compose.yaml korrigieren, docker compose down -v (Achtung: löscht das DB-Volume!), dann neu starten.
Modelle werden bei jedem Neustart neu heruntergeladen: Das Volume khoj_models wurde versehentlich gelöscht oder nicht korrekt gemountet. Fix: Prüfen mit docker volume ls | grep khoj – alle vier Volumes sollten existieren.

Häufige Fragen

Kann Khoj vollständig offline ohne Cloud-APIs betrieben werden?

Ja. Ollama auf dem Host installieren, ein Modell laden (ollama pull llama3.1), OPENAI_BASE_URL=http://host.docker.internal:11434/v1/ in der .env setzen und im Admin-Panel unter „AI Model API" ein neues Modell vom Typ openai mit dem Ollama-Modellnamen registrieren. Nach dem initialen Image- und Modell-Download ist kein Internetzugang mehr notwendig.

Welche Dokumente kann Khoj indizieren?

PDF, Markdown (.md), Word-Dokumente (.docx), Notion-Seiten (via Plugin), Org-Mode-Dateien sowie Webseiten. Für Obsidian, Emacs und Notion gibt es offizielle Plugins, die Änderungen automatisch synchronisieren.

Den Flag --anonymous-mode aus dem command-Feld in der compose.yaml entfernen. Danach muss Authentifizierung konfiguriert werden: entweder Magic Links via Resend API (RESEND_API_KEY setzen) oder Google OAuth (GOOGLE_CLIENT_ID und GOOGLE_CLIENT_SECRET – dafür wird das Image ghcr.io/khoj-ai/khoj-cloud:latest benötigt).

Was macht der Terrarium-Service und kann ich ihn weglassen?

Terrarium ist Khojs isolierte Python-Code-Sandbox, die es dem Assistenten ermöglicht, Python-Code sicher auszuführen – etwa für Datenanalysen oder Berechnungen auf Knopfdruck. Ohne diesen Service ist Code-Ausführung deaktiviert, aber Khoj selbst startet und läuft problemlos. Wer den Service nicht braucht, kann ihn aus der compose.yaml entfernen und KHOJ_TERRARIUM_URL weglassen.

Wie aktualisiere ich Khoj auf die neueste Version?

docker compose pull && docker compose up -d im Projektordner ausführen. Da alle Daten in benannten Volumes liegen, bleiben Konfiguration, Datenbank und Modell-Cache vollständig erhalten. Es empfiehlt sich, vor dem Update ein Backup des khoj_db-Volumes anzulegen.

Wie erreiche ich Khoj von außen sicher?

Für den Remote-Zugriff im privaten Netz empfiehlt sich Tailscale oder Headscale als selbstgehostetes Mesh-VPN. Für einen öffentlichen Zugang KHOJ_DOMAIN auf die eigene Domain setzen und einen Reverse Proxy mit Let's Encrypt davor schalten. Niemals den Port 42110 direkt ohne Authentifizierung ans Internet exponieren, solange --anonymous-mode aktiv ist.

Fazit

Khoj ist eine der ausgereiftesten Open-Source-Lösungen für einen persönlichen KI-Assistenten mit eigener Wissensdatenbank. Der Docker-Compose-Stack ist in unter 30 Minuten betriebsbereit und deckt mit PostgreSQL+pgvector, SearxNG und Terrarium direkt die wichtigsten Abhängigkeiten ab. Besonders die Ollama-Integration macht den Einsatz datenschutzkonform und ohne laufende Cloud-Kosten möglich – das ist für DSGVO-bewusste KMU ein echter Vorteil gegenüber Cloud-Lösungen.

Wer tiefer in RAG-Systeme einsteigen möchte, findet in der Anleitung Lokales RAG-System mit Qdrant und Embeddings einen guten Einstieg in die zugrundeliegenden Konzepte.

Weiterführende Anleitungen und Quellen

Offizielle Quellen: Khoj Self-Host Setup Dokumentation | Khoj GitHub Repository | Khoj Ollama-Integration