Khoj Docker 설치 가이드: AI 세컨드 브레인 ⋆ Blog * JackerLab

개요

Khoj는 AI 세컨드 브레인(두 번째 뇌)으로, 개인 AI 어시스턴트입니다. 웹과 문서에서 답변을 얻고, 커스텀 에이전트를 만들고, 자동화를 스케줄하고, 딥 리서치를 수행합니다. Ollama, OpenAI, Claude, Gemini 등 모든 LLM을 지원하며, Obsidian, Emacs, WhatsApp 등 다양한 클라이언트에서 접근할 수 있습니다.

항목	내용
GitHub	https://github.com/khoj-ai/khoj
공식 사이트	https://khoj.dev
문서	https://docs.khoj.dev
라이선스	AGPL-3.0
GitHub Stars	18K+

Khoj란?

왜 Khoj인가?

❌ 기존 AI 어시스턴트의 한계:
   - 개인 문서 접근 불가
   - 자동화 기능 없음
   - 단순 채팅만 가능

✅ Khoj의 해결책:
   - 문서 + 웹 통합 검색
   - 커스텀 에이전트 생성
   - 자동화 스케줄링
   - 딥 리서치 (/research)
   - 개인 뉴스레터 & 알림

핵심 슬로건

"Your AI Second Brain"
- 웹 + 문서에서 답변
- 커스텀 에이전트 구축
- 자동화 & 스케줄링
- 딥 리서치 모드
- 어디서나 접근 (브라우저, Obsidian, WhatsApp)

아키텍처

┌─────────────────────────────────────────┐
│         Khoj Clients                     │
│  (브라우저, Obsidian, Emacs, WhatsApp)   │
├─────────────────────────────────────────┤
│         Khoj Server (Django)             │
│   (에이전트, 자동화, 검색, 채팅)          │
├──────────────┬──────────────────────────┤
│  PostgreSQL  │     SearXNG    │ Terrarium│
│ (pgvector)   │   (웹 검색)    │ (샌드박스)|
└──────────────┴──────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────┐
│  OpenAI │ Claude │ Gemini │ Ollama │ ...│
└─────────────────────────────────────────┘

주요 기능

💬 채팅 & 검색

기능	설명
웹 검색	SearXNG로 인터넷 검색
문서 검색	PDF, Markdown, Word, Notion
이미지 검색	이미지 분석 및 검색
딥 리서치	`/research` 명령으로 심층 조사

🤖 LLM 지원

제공자	지원 모델
OpenAI	GPT-4o, GPT-4, GPT-3.5
Anthropic	Claude 3.5, Claude 3
Google	Gemini Pro
Ollama	Llama, Qwen, Mistral, DeepSeek
vLLM	OpenAI 호환
LM Studio	로컬 GUI

🧩 에이전트 & 자동화

기능	설명
커스텀 에이전트	성격, 도구, 지식 베이스 설정
자동화 스케줄링	반복 작업 자동 실행
개인 뉴스레터	관심 주제 뉴스 이메일
스마트 알림	조건부 알림

📚 문서 지원

형식	지원
PDF	✅
Markdown	✅
Word (DOCX)	✅
Org-mode	✅
Notion	✅
이미지	✅

📱 클라이언트

클라이언트	설명
웹 브라우저	기본 UI
Obsidian	플러그인
Emacs	패키지
Desktop	데스크톱 앱
WhatsApp	메신저 연동
Phone	모바일 앱

🔧 고급 기능

기능	설명
코드 실행	Terrarium 샌드박스
이미지 생성	DALL-E, Stable Diffusion
음성 대화	TTS/STT
멀티미디어	이미지, 음성 처리

시스템 요구 사항

항목	최소	권장
CPU	2 코어	4+ 코어
RAM	4GB	8GB+
저장소	10GB	20GB+
포트	42110	–

Docker 설치

방법 1: 공식 Docker Compose (권장)

# 디렉토리 생성 및 docker-compose.yml 다운로드
mkdir ~/.khoj && cd ~/.khoj
wget https://raw.githubusercontent.com/khoj-ai/khoj/master/docker-compose.yml

# 환경 변수 설정 (docker-compose.yml 편집)
# KHOJ_ADMIN_PASSWORD, KHOJ_DJANGO_SECRET_KEY 설정

# 시작
docker-compose up -d

접속: http://localhost:42110

방법 2: 기본 Docker Compose

# docker-compose.yml
services:
  server:
    image: ghcr.io/khoj-ai/khoj-cloud:latest
    container_name: khoj
    restart: unless-stopped
    ports:
      - "42110:42110"
    environment:
      - KHOJ_ADMIN_EMAIL=admin@example.com
      - KHOJ_ADMIN_PASSWORD=your-secure-password
      - KHOJ_DJANGO_SECRET_KEY=your-secret-key-at-least-50-chars
      - KHOJ_DEBUG=False
      - KHOJ_DOMAIN=localhost
    volumes:
      - ./khoj_data:/root/.khoj
    depends_on:
      - database

  database:
    image: pgvector/pgvector:pg15
    container_name: khoj-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=khoj
      - POSTGRES_USER=khoj
      - POSTGRES_PASSWORD=khoj
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

방법 3: 전체 스택 (SearXNG + Terrarium)

# docker-compose.yml
services:
  server:
    image: ghcr.io/khoj-ai/khoj-cloud:latest
    container_name: khoj
    restart: unless-stopped
    ports:
      - "42110:42110"
    environment:
      - KHOJ_ADMIN_EMAIL=admin@example.com
      - KHOJ_ADMIN_PASSWORD=your-secure-password
      - KHOJ_DJANGO_SECRET_KEY=your-secret-key
      - KHOJ_DOMAIN=localhost
      - KHOJ_SEARXNG_URL=http://searxng:8080
      - KHOJ_TERRARIUM_URL=http://terrarium:8080
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./khoj_data:/root/.khoj
    depends_on:
      - database
      - searxng
      - terrarium

  database:
    image: pgvector/pgvector:pg15
    container_name: khoj-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=khoj
      - POSTGRES_USER=khoj
      - POSTGRES_PASSWORD=khoj
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

  searxng:
    image: searxng/searxng:latest
    container_name: khoj-searxng
    restart: unless-stopped
    volumes:
      - ./searxng:/etc/searxng:rw

  terrarium:
    image: ghcr.io/khoj-ai/terrarium:latest
    container_name: khoj-terrarium
    restart: unless-stopped

방법 4: Ollama 로컬 LLM

# docker-compose.yml
services:
  server:
    image: ghcr.io/khoj-ai/khoj-cloud:latest
    container_name: khoj
    restart: unless-stopped
    ports:
      - "42110:42110"
    environment:
      - KHOJ_ADMIN_EMAIL=admin@example.com
      - KHOJ_ADMIN_PASSWORD=your-secure-password
      - KHOJ_DJANGO_SECRET_KEY=your-secret-key
      - OPENAI_BASE_URL=http://host.docker.internal:11434/v1
    volumes:
      - ./khoj_data:/root/.khoj
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on:
      - database

  database:
    image: pgvector/pgvector:pg15
    container_name: khoj-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=khoj
      - POSTGRES_USER=khoj
      - POSTGRES_PASSWORD=khoj
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ./ollama:/root/.ollama

방법 5: OpenAI 사용

# docker-compose.yml 환경 변수
environment:
  - OPENAI_API_KEY=sk-your-openai-api-key

방법 6: Anthropic Claude

# docker-compose.yml 환경 변수
environment:
  - ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

방법 7: Google Gemini

# docker-compose.yml 환경 변수
environment:
  - GEMINI_API_KEY=your-gemini-api-key

방법 8: Traefik + HTTPS

# docker-compose.yml
services:
  server:
    image: ghcr.io/khoj-ai/khoj-cloud:latest
    container_name: khoj
    restart: unless-stopped
    environment:
      - KHOJ_ADMIN_EMAIL=admin@example.com
      - KHOJ_ADMIN_PASSWORD=your-secure-password
      - KHOJ_DJANGO_SECRET_KEY=your-secret-key
      - KHOJ_DOMAIN=khoj.example.com
      - KHOJ_NO_HTTPS=False
    volumes:
      - ./khoj_data:/root/.khoj
    networks:
      - traefik_network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.khoj.rule=Host(`khoj.example.com`)"
      - "traefik.http.routers.khoj.entrypoints=websecure"
      - "traefik.http.routers.khoj.tls.certresolver=letsencrypt"
      - "traefik.http.services.khoj.loadbalancer.server.port=42110"

networks:
  traefik_network:
    external: true

환경 변수

필수 설정

변수	설명
`KHOJ_ADMIN_EMAIL`	관리자 이메일
`KHOJ_ADMIN_PASSWORD`	관리자 비밀번호
`KHOJ_DJANGO_SECRET_KEY`	Django 시크릿 (50자+)

서버 설정

변수	설명	기본값
`KHOJ_DOMAIN`	외부 접근 도메인	`localhost`
`KHOJ_ALLOWED_DOMAIN`	허용 도메인	–
`KHOJ_DEBUG`	디버그 모드	`False`
`KHOJ_NO_HTTPS`	HTTPS 비활성화	`False`

LLM 제공자

변수	설명
`OPENAI_API_KEY`	OpenAI API 키
`OPENAI_BASE_URL`	OpenAI 호환 URL (Ollama 등)
`ANTHROPIC_API_KEY`	Anthropic API 키
`GEMINI_API_KEY`	Google Gemini API 키

서비스 연동

변수	설명
`KHOJ_SEARXNG_URL`	SearXNG 웹 검색 URL
`KHOJ_TERRARIUM_URL`	Terrarium 샌드박스 URL
`E2B_API_KEY`	E2B 원격 샌드박스
`SERPER_DEV_API_KEY`	Serper 웹 검색
`FIRECRAWL_API_KEY`	Firecrawl 웹 크롤링
`OLOSTEP_API_KEY`	Olostep 웹페이지 읽기

인증

변수	설명
`GOOGLE_CLIENT_ID`	Google OAuth ID
`GOOGLE_CLIENT_SECRET`	Google OAuth 시크릿

초기 설정

1) 첫 접속

URL: http://localhost:42110
→ 관리자 계정으로 로그인

2) 관리자 패널

URL: http://localhost:42110/server/admin
→ LLM 모델 설정
→ 사용자 관리
→ 에이전트 설정

3) 문서 업로드

웹 UI에서 문서 업로드
지원 형식: PDF, Markdown, Word, Notion
자동 인덱싱 및 벡터화

4) 채팅 시작

질문 예시:

“내 문서에서 프로젝트 일정을 찾아줘”
“최신 AI 뉴스 요약해줘”
/research AI 에이전트 트렌드 2025

사용 가이드

딥 리서치 모드

메시지 앞에 /research 추가:

/research 2025년 AI 에이전트 기술 동향

심층 조사 + 종합 보고서 생성

커스텀 에이전트 만들기

Settings → Agents
Create Agent 클릭
설정:
- 이름, 성격
- 사용할 LLM
- 도구 (웹 검색, 코드 실행 등)
- 지식 베이스

자동화 스케줄링

Automations 메뉴
New Automation 클릭
설정:
- 트리거 (시간, 조건)
- 작업 (검색, 요약, 알림)
- 전달 방법 (이메일, WhatsApp)

Obsidian 연동

Obsidian에서 Community Plugins
“Khoj” 검색 및 설치
설정에서 서버 URL 입력
노트에서 바로 Khoj 질문

WhatsApp 연동

관리자 패널에서 WhatsApp 설정
Twilio 또는 WhatsApp Business API 연결
번호로 메시지 보내기

백업 및 복원

데이터 구조

./
├── khoj_data/           # Khoj 데이터
├── postgres_data/       # PostgreSQL + pgvector
└── searxng/             # SearXNG 설정

백업

# 컨테이너 정지
docker-compose down

# 전체 백업
tar -czvf khoj-backup-$(date +%Y%m%d).tar.gz \
  khoj_data/ postgres_data/

# PostgreSQL 덤프 (선택)
docker exec khoj-db pg_dump -U khoj khoj > khoj_db.sql

# 재시작
docker-compose up -d

복원

tar -xzvf khoj-backup.tar.gz
docker-compose up -d

업데이트

cd ~/.khoj

# 최신 이미지 가져오기
docker-compose pull

# 재빌드 및 시작
docker-compose up --build -d

트러블슈팅

Ollama 연결 안 됨

Linux에서 host.docker.internal 사용:

extra_hosts:
  - "host.docker.internal:host-gateway"

OPENAI_BASE_URL 설정:

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

메모리 부족

"Killed" 메시지 → RAM 부족

해결: Docker 메모리 한도 증가 (최소 4GB)

CSRF 오류

KHOJ_DOMAIN을 외부 접근 도메인으로 설정:

environment:
  - KHOJ_DOMAIN=your-server-ip-or-domain

데이터베이스 연결 오류

PostgreSQL 로그 확인:

docker logs khoj-db

대안 비교

기능	Khoj	Perplexica	AnythingLLM
웹 검색	✅ SearXNG	✅ SearXNG	❌
문서 RAG	✅	❌	✅
에이전트	✅ 커스텀	❌	✅
자동화	✅ 스케줄링	❌	❌
딥 리서치	✅ /research	✅	❌
Obsidian	✅ 플러그인	❌	❌
WhatsApp	✅	❌	❌
코드 실행	✅ Terrarium	❌	❌
이미지 생성	✅	❌	❌

선택 가이드

용도	추천
개인 AI 어시스턴트	Khoj
AI 검색 엔진	Perplexica
문서 Q&A	AnythingLLM
자동화 + 에이전트	Khoj
Obsidian 연동	Khoj

활용 사례

1. 개인 지식 관리

구성:

문서, 노트 업로드
Obsidian 플러그인 연동
로컬 Ollama로 프라이버시

결과: 개인 세컨드 브레인

2. 연구 어시스턴트

구성:

/research 딥 리서치 모드
학술 논문 업로드
웹 검색 통합

결과: 심층 연구 보고서 자동 생성

3. 뉴스 모니터링

구성:

자동화 스케줄링
관심 주제 설정
이메일 뉴스레터 전송

결과: 매일 맞춤 뉴스 브리핑

4. 팀 지식 베이스

구성:

회사 문서 업로드
커스텀 에이전트 (부서별)
멀티 유저 접근

결과: 팀 공용 AI 어시스턴트

5. 개발자 도우미

구성:

코드 문서, README 업로드
Terrarium 코드 실행
GitHub 연동

결과: 코드 Q&A + 실행

마무리

Khoj는 AI 세컨드 브레인으로, 단순한 채팅을 넘어 개인 AI 어시스턴트 역할을 합니다. 웹과 문서 검색, 커스텀 에이전트, 자동화, 딥 리서치를 모두 지원합니다. Obsidian, WhatsApp 등 다양한 클라이언트에서 접근할 수 있어 어디서나 AI 비서를 활용할 수 있습니다.

핵심 장점

장점	설명
세컨드 브레인	개인 AI 어시스턴트
웹 + 문서	통합 검색
커스텀 에이전트	성격, 도구, 지식 설정
자동화	스케줄링, 뉴스레터
딥 리서치	/research 심층 조사
멀티 클라이언트	브라우저, Obsidian, WhatsApp
다중 LLM	OpenAI, Claude, Ollama
코드 실행	Terrarium 샌드박스

이런 분께 추천

개인 AI 어시스턴트가 필요한 분
문서 + 웹 통합 검색을 원하는 분
자동화된 연구/모니터링이 필요한 분
Obsidian 사용자
WhatsApp으로 AI를 사용하고 싶은 분

개요

Khoj란?

왜 Khoj인가?

핵심 슬로건

아키텍처

주요 기능

💬 채팅 & 검색

🤖 LLM 지원

🧩 에이전트 & 자동화

📚 문서 지원

📱 클라이언트

🔧 고급 기능

시스템 요구 사항

Docker 설치

방법 1: 공식 Docker Compose (권장)

방법 2: 기본 Docker Compose

방법 3: 전체 스택 (SearXNG + Terrarium)

방법 4: Ollama 로컬 LLM

방법 5: OpenAI 사용

방법 6: Anthropic Claude

방법 7: Google Gemini

방법 8: Traefik + HTTPS

환경 변수

필수 설정

서버 설정

LLM 제공자

서비스 연동

인증

초기 설정

1) 첫 접속

2) 관리자 패널

3) 문서 업로드

4) 채팅 시작

사용 가이드

딥 리서치 모드

커스텀 에이전트 만들기

자동화 스케줄링

Obsidian 연동

WhatsApp 연동

백업 및 복원

데이터 구조

백업

복원

업데이트

트러블슈팅

Ollama 연결 안 됨

메모리 부족

CSRF 오류

데이터베이스 연결 오류

대안 비교

선택 가이드

활용 사례

1. 개인 지식 관리

2. 연구 어시스턴트

3. 뉴스 모니터링

4. 팀 지식 베이스

5. 개발자 도우미

마무리

핵심 장점

이런 분께 추천

댓글 남기기 응답 취소