Deploying Khoj

Introduction

Khoj is a self-hostable AI second brain that turns any online or local LLM into your personal, autonomous AI assistant. It can answer questions from your documents, the web, or both, while supporting deep research, custom agents, and scheduled automations.

Unlike cloud-only AI assistants, Khoj gives you complete control over your data and choice of AI models. Connect it to GPT-4, Claude, Gemini, or run fully local with Llama, Qwen, or Mistral through Ollama. Your notes, documents, and conversations stay on your infrastructure.

Key highlights of Khoj:

Multi-Model Support: Use OpenAI, Anthropic, Google, or local LLMs via Ollama
Document Search: Index and query your notes, PDFs, and documents
Web Search: Get answers informed by real-time web results
Custom Agents: Build specialized AI agents for specific tasks
Scheduled Automations: Set up recurring AI tasks and reminders
Deep Research: Multi-step research with source citations
Multiple Interfaces: Web, desktop apps, Obsidian/Emacs plugins, WhatsApp
Python Sandbox: Execute code safely within conversations
Self-Hosted: Complete data ownership and privacy
Conversation Memory: Context-aware responses across sessions

This guide walks through deploying Khoj on Klutch.sh using Docker, configuring AI model connections, and setting up your personal knowledge base.

Why Deploy Khoj on Klutch.sh

Deploying Khoj on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds and deploys Khoj from your Dockerfile without complex orchestration.

Persistent Storage: Attach persistent volumes for your PostgreSQL database and indexed documents.

HTTPS by Default: Secure connections for web access and API integrations with automatic SSL certificates.

Environment Variable Management: Securely store API keys for OpenAI, Anthropic, or other AI services.

Remote Access: Query your knowledge base from anywhere through the web interface or mobile apps.

Always-On Availability: Your AI assistant is available 24/7 for questions, research, and automations.

Prerequisites

Before deploying Khoj on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and containerization concepts
(Optional) API keys for OpenAI, Anthropic, or Google AI

Preparing Your Repository

To deploy Khoj on Klutch.sh, create a GitHub repository containing your Docker configuration.

Repository Structure

khoj-deploy/
├── docker-compose.yml
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Khoj uses Docker Compose for its multi-service architecture. For Klutch.sh, you can use the all-in-one image:

FROM ghcr.io/khoj-ai/khoj:latest

# Environment variables configured via Klutch.sh dashboard
# KHOJ_ADMIN_EMAIL - Admin email
# KHOJ_ADMIN_PASSWORD - Admin password
# KHOJ_DJANGO_SECRET_KEY - Django secret key
# OPENAI_API_KEY - Optional OpenAI API key
# ANTHROPIC_API_KEY - Optional Anthropic API key

EXPOSE 42110

Environment Variables Reference

Variable	Required	Description
`KHOJ_ADMIN_EMAIL`	Yes	Admin account email
`KHOJ_ADMIN_PASSWORD`	Yes	Admin account password
`KHOJ_DJANGO_SECRET_KEY`	Yes	Django secret for encryption
`KHOJ_DOMAIN`	No	Your domain for remote access
`OPENAI_API_KEY`	No	OpenAI API key for GPT models
`ANTHROPIC_API_KEY`	No	Anthropic API key for Claude
`GEMINI_API_KEY`	No	Google API key for Gemini
`OPENAI_BASE_URL`	No	Custom endpoint for Ollama/vLLM
`GOOGLE_CLIENT_ID`	No	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Deploying Khoj on Klutch.sh

Generate Django Secret Key

openssl rand -base64 32

Save this for environment variables.

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore
git commit -m "Initial Khoj deployment configuration"
git remote add origin https://github.com/yourusername/khoj-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “khoj” or “ai-assistant”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Khoj repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 42110

Set Environment Variables

Variable	Value
`KHOJ_ADMIN_EMAIL`	Your admin email
`KHOJ_ADMIN_PASSWORD`	A secure password
`KHOJ_DJANGO_SECRET_KEY`	Your generated secret
`KHOJ_DOMAIN`	`your-app-name.klutch.sh`
`OPENAI_API_KEY`	Your OpenAI key (optional)
`ANTHROPIC_API_KEY`	Your Anthropic key (optional)

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
`/root/.khoj`	10 GB	Database, indexes, and configuration

Deploy Your Application

Click Deploy to start the build process.

Access Khoj

Once deployment completes, access Khoj at https://your-app-name.klutch.sh.

Initial Setup and Configuration

Accessing the Admin Panel

Navigate to https://your-app-name.klutch.sh/admin
Log in with your admin credentials
Configure AI models and settings

Configuring Chat Models

Set up your AI models:

Go to Admin > Chat Model Options
Add your preferred models (GPT-4, Claude, etc.)
Configure API keys if not set via environment variables
Set default model preferences

Using Local LLMs with Ollama

For fully private AI:

Set OPENAI_BASE_URL to your Ollama server
Configure model names matching your Ollama installation
Enjoy private, local AI processing

Indexing Your Documents

Add your knowledge base:

Navigate to Files in the web interface
Upload documents (PDF, Markdown, text files)
Khoj will automatically index for semantic search
Query your documents through chat

Building Custom Agents

Creating Agents

Build specialized assistants:

Go to Agents in settings
Create a new agent with a specific persona
Define the agent’s knowledge sources
Configure behavioral instructions
Use the agent for domain-specific queries

Scheduling Automations

Set up recurring tasks:

Navigate to Automations
Create scheduled queries (daily summaries, research tasks)
Configure notification preferences
Khoj will run tasks automatically

Client Applications

Desktop Apps

Khoj provides desktop applications for:

Windows
macOS
Linux

Download from the Khoj website and configure with your server URL.

Editor Plugins

Integrate with your workflow:

Obsidian Plugin: Query Khoj from your notes
Emacs Package: AI assistance in your editor

Mobile Access

Access via:

Web interface (mobile-optimized)
WhatsApp integration (with configuration)

Production Best Practices

Data Protection

Regular Backups: Back up the persistent volume
Document Security: Consider what documents you index
API Key Rotation: Regularly rotate AI service keys

Performance Optimization

Model Selection: Choose models based on speed/quality tradeoffs
Index Management: Keep indexed documents relevant
Resource Allocation: Increase resources for larger knowledge bases

Troubleshooting Common Issues

AI Not Responding

Solutions:

Verify API keys are correctly configured
Check model configuration in admin panel
Ensure selected model is available
Review application logs for API errors

Documents Not Searchable

Solutions:

Verify upload completed successfully
Check supported file formats
Allow time for indexing to complete
Trigger manual reindexing if needed

Additional Resources

Conclusion

Deploying Khoj on Klutch.sh gives you a powerful, self-hosted AI second brain with automatic builds, persistent storage, and secure HTTPS access. Whether using cloud AI services or running fully local with Ollama, Khoj provides the flexibility to build your perfect AI assistant while maintaining complete data ownership.

With document search, web integration, custom agents, and scheduled automations, Khoj on Klutch.sh becomes your always-available AI partner for research, learning, and productivity.