https://github.com/JSONbored/khoj-aio
Beginner-friendly All-in-One Unraid container for Khoj, a self-hosted AI second brain. Bundles the Khoj web app with an internal PostgreSQL database in a single container, while still supporting local or hosted LLMs, external search backends, reverse proxies, and advanced power-user overrides.
https://github.com/JSONbored/khoj-aio
ai anthropic assistant container docker gemini homelab khoj knowledge-base llm ollama openai pgvector postgresql rag search second-brain self-hosted unraid unraid-template
Last synced: 16 days ago
JSON representation
Beginner-friendly All-in-One Unraid container for Khoj, a self-hosted AI second brain. Bundles the Khoj web app with an internal PostgreSQL database in a single container, while still supporting local or hosted LLMs, external search backends, reverse proxies, and advanced power-user overrides.
- Host: GitHub
- URL: https://github.com/JSONbored/khoj-aio
- Owner: JSONbored
- Created: 2026-03-28T15:34:47.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-02T09:02:54.000Z (19 days ago)
- Last Synced: 2026-05-02T10:29:35.772Z (19 days ago)
- Topics: ai, anthropic, assistant, container, docker, gemini, homelab, khoj, knowledge-base, llm, ollama, openai, pgvector, postgresql, rag, search, second-brain, self-hosted, unraid, unraid-template
- Language: Python
- Homepage: https://aethereal.dev
- Size: 229 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Support: docs/support-thread-template.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# khoj-aio
An Unraid-first, single-container deployment of [Khoj](https://github.com/khoj-ai/khoj) for people who want the easiest reliable self-hosted install without manually wiring PostgreSQL or reworking the upstream compose stack for Unraid.
`khoj-aio` keeps the critical first-boot dependency bundled: PostgreSQL with `pgvector`. The wrapper is opinionated for a predictable beginner install, but it does not hide the real tradeoffs: remote exposure still needs correct auth and domain settings, operator/computer features carry meaningful security implications, and advanced search/sandbox/provider integrations still consume real resources.
## What This Image Includes
- Khoj web UI and API on port `42110`
- Embedded PostgreSQL with `pgvector`
- Persistent appdata paths for config, database state, and model caches
- First-run generation for `KHOJ_DJANGO_SECRET_KEY`, `KHOJ_ADMIN_PASSWORD`, and the internal DB password when left unset
- Unraid CA template at [khoj-aio.xml](khoj-aio.xml)
## Beginner Install
If you want the simplest supported path:
1. Install the Unraid template.
2. Leave the default appdata paths in place.
3. Optionally set `KHOJ_ADMIN_EMAIL`, `KHOJ_ADMIN_PASSWORD`, and `KHOJ_DJANGO_SECRET_KEY`.
4. Leave `KHOJ_ANONYMOUS_MODE=true` for the default private single-user flow.
5. Start the container and wait for first-boot initialization to complete.
6. Open the web UI on port `42110`.
7. Restart the container once after the initial setup so all settings are fully applied.
If you leave the admin password or Django secret blank, the wrapper generates secure values and writes them to `/root/.khoj/aio/generated.env` inside your mapped config path.
## Power User Surface
This repo is deliberately not a stripped-down wrapper. The template now tracks the practical self-hosted environment surface exposed by upstream source and docs, plus AIO-specific controls for the bundled database flow. In Advanced View you can:
- move PostgreSQL out of the container with the standard `POSTGRES_*` settings
- point Khoj at OpenAI, Anthropic, Gemini, Ollama, LM Studio, LiteLLM, vLLM, or other OpenAI-compatible endpoints
- configure SearxNG, Serper, Google Search, Firecrawl, Olostep, or Exa for search and webpage reading
- enable Terrarium or E2B code execution
- tune operator/computer behavior and optionally mount the Docker socket for that path
- configure Resend, Google auth, Notion OAuth, Twilio, and AWS-backed upload storage
- expose runtime tuning knobs like Gunicorn worker/timeouts and research iteration limits
The wrapper still defaults to the internal bundled database and a minimal beginner-safe install path so new Unraid users are not forced into extra containers on day one.
## Runtime Notes
- Upstream Khoj releases are currently tagged as beta releases. This wrapper tracks the latest published production-facing release line rather than floating `latest`.
- The internal PostgreSQL service is bound to loopback inside the container and now uses a generated per-install password instead of a fixed hardcoded credential.
- The bundled database user is no longer created as a PostgreSQL superuser; the wrapper creates the `vector` extension as `postgres` during initialization instead.
- Search, webpage-reading, and code-execution integrations are intentionally optional. The AIO image does not currently bundle SearxNG or Terrarium by default because that would materially increase resource cost and attack surface for all users.
- If you expose Khoj beyond your LAN, you should set strong credentials, set `KHOJ_DOMAIN` and `KHOJ_ALLOWED_DOMAIN` correctly, and strongly consider disabling anonymous mode.
## Publishing and Releases
- Wrapper releases use the upstream version plus an AIO revision, such as `2.0.0-beta.28-aio.1`.
- Upstream monitoring, release preparation, registry publishing, and catalog sync are owned by `aio-fleet` from `.aio-fleet.yml`.
- Changelog generation and XML `` sync are run centrally by `aio-fleet` during release preparation.
- `main` publishes `latest`, the pinned upstream version tag, an explicit AIO packaging line tag, and `sha-`.
- Publish jobs require Docker Hub credentials and push the CA-facing Docker Hub tags directly.
See [docs/releases.md](docs/releases.md) for the central release process details.
## Validation
Required local validation is `aio-fleet` first:
```bash
python3 -m venv .venv-local
.venv-local/bin/pip install -e "../aio-fleet[app-tests]"
.venv-local/bin/pytest tests/integration -m integration --junit-xml=reports/pytest-integration.xml -o junit_family=xunit1
cd ../aio-fleet
.venv/bin/python -m aio_fleet validate-repo --repo khoj-aio --repo-path ../khoj-aio
.venv/bin/python -m aio_fleet trunk run --repo khoj-aio --repo-path ../khoj-aio --no-fix
```
CI cost model:
- relevant PRs and `main` pushes run the fast validation layers first
- Docker-backed integration tests run for build-relevant changes, for `main` release-metadata commits when publish is still in play, and for manual dispatches
- image publish stays gated behind the integration suite instead of treating skipped integration as acceptable
- local Docker validation stays explicit instead of hiding inside every routine commit hook
## Support
- Repo issues: [JSONbored/khoj-aio issues](https://github.com/JSONbored/khoj-aio/issues)
- Upstream app: [khoj-ai/khoj](https://github.com/khoj-ai/khoj)
## Funding
If this work saves you time, support it here:
- [GitHub Sponsors](https://github.com/sponsors/JSONbored)
- [Ko-fi](https://ko-fi.com/jsonbored)
- [Buy Me a Coffee](https://buymeacoffee.com/jsonbored)
## Star History
[](https://star-history.com/#JSONbored/khoj-aio&Date)