Khoj AIO (All-in-One) for Unraid

An ultra-simplified, self-contained deployment of Khoj designed for Unraid users who want a clean, beginner-friendly install without giving up advanced controls.

---

Instead of making newcomers wire up a multi-container docker-compose stack by hand, this AIO wrapper runs Khoj inside a single Unraid container and manages an internal PostgreSQL database automatically for the easiest possible first boot. Advanced users can still override the defaults and point Khoj at external model providers, search backends, code sandboxes, reverse proxies, or an external PostgreSQL database.

What's Inside the AIO Container

This image uses s6-overlay v3 to wrap the upstream ghcr.io/khoj-ai/khoj image with a more Unraid-friendly startup flow:

• The Khoj web app and API
• An internally managed PostgreSQL database for a true single-container setup
• Built-in pgvector support so Khoj migrations and embeddings work correctly
• First-run credential bootstrapping for KHOJ_DJANGO_SECRET_KEY and admin password if you leave them blank
• Persistent config and model cache storage mapped into Unraid appdata

This keeps the install simple for beginners while preserving the upstream environment variables and admin-panel driven customization model for power users.

Installation (For Beginners)

1. Add this repository to Unraid Community Applications, or import the XML directly.
2. Install Khoj AIO.
3. Leave the default paths alone unless you know you want them elsewhere.
4. Optionally set your own Admin Email, Admin Password, and Django Secret Key.
5. Click Apply.

If you leave the password or secret blank, the container will generate secure values on first boot and save them under /root/.khoj/aio/generated.env inside your mapped config folder.

Wait about 30-60 seconds on the first launch. Once the logs show that Khoj is ready, open the WebUI on port 42110.

After the very first boot, restart the container once. Khoj's self-host docs recommend a restart after initial setup so all settings are fully applied.

Power User Configuration

This template is intentionally beginner-first, but it does not lock you into beginner-only behavior.

If you click Show more settings... in Unraid, you can configure:

• OpenAI-compatible local providers like Ollama, vLLM, LocalAI, or compatible gateways
• External PostgreSQL instead of the internal AIO database
• Remote access, reverse proxy, and custom domain handling
• Magic link authentication with Resend
• External web search and code execution backends and here
• Telemetry disablement and voice/TTS options

Data Persistence

Your data survives container updates because the important paths are mapped to Unraid storage:

• Khoj config and uploads: /mnt/user/appdata/khoj-aio/config
• Internal PostgreSQL data: /mnt/user/appdata/khoj-aio/postgres
• Hugging Face model cache: /mnt/user/appdata/khoj-aio/models/huggingface
• SentenceTransformer cache: /mnt/user/appdata/khoj-aio/models/sentence-transformers

If you back up /mnt/user/appdata/khoj-aio, you are backing up the important state for this deployment.

Notes

• This AIO image manages its own internal PostgreSQL database inside the container so first boot works cleanly without extra sidecars.
• Upstream docker-compose also includes separate SearxNG and Terrarium containers. In this AIO design those are optional advanced integrations, not first-boot requirements.
• Basic webpage reading still works out of the box, since Khoj can fetch pages directly without an external scraper.
• For remote IP/domain access, you should set KHOJ_DOMAIN and, when needed, KHOJ_ALLOWED_DOMAIN to avoid admin-panel CSRF or DisallowedHost issues.
• Google OAuth is not exposed in this base AIO because upstream documents it against the khoj-cloud prod image rather than the standard self-hosted image.

Validation

This repository has been validated with repeated local Docker smoke tests against the live upstream image. The validation path covered:

• image build success on the AIO wrapper
• first boot from empty config and empty PostgreSQL data
• automatic admin and secret bootstrap
• PostgreSQL startup and pgvector extension availability
• successful Khoj migrations and ready state
• HTTP responses on the published web port

Versioning And Upstream Tracking

Khoj-AIO now pins a specific upstream Khoj release and the exact upstream image digest that this wrapper builds from. The repository also includes an upstream monitor workflow that checks for new upstream Khoj releases and opens an update PR instead of silently drifting.

Published image tags are intended to include:

• latest for the default install path
• exact upstream version tags like 2.0.0-beta.28
• wrapper tags like 2.0.0-beta.28-aio-v1
• sha-<commit> tags for exact reproducibility

License and Acknowledgements

• The upstream application is maintained by the khoj-ai/khoj team.
• Khoj is licensed under AGPL-3.0.
• This repository is an Unraid-focused AIO wrapper intended to make self-hosting easier for homelab users.

Star History