khoj/documentation/docs/get-started/setup.mdx

---
sidebar_position: 1
---

# Self-Host
Learn about how to self-host Khoj on your own machine.

Benefits to self-hosting:
1. **Privacy**: Your data will never have to leave your private network. You can even use Khoj without an internet connection if deployed on your personal computer.
2. **Customization**: You can customize Khoj to your liking, from models, to host URL, to feature enablement.

```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```

## Setup
These are the general setup instructions for self-hosted Khoj.
You can install the Khoj server using either Docker or Pip.

:::info[Offline Model + GPU]
If you want to use the offline chat model and you have a GPU, you should use Installation Option 2  - local setup via the Python package directly. Our Docker image doesn't currently support running the offline chat model on GPU, making inference times really slow.
:::

### 1A. Install Method 1: Docker

#### Prerequisites
1. Install Docker Engine. See [official instructions](https://docs.docker.com/engine/install/).
2. Ensure you have Docker Compose. See [official instructions](https://docs.docker.com/compose/install/).

#### Setup

1. Get the sample docker-compose file [from Github](https://github.com/khoj-ai/khoj/blob/master/docker-compose.yml).
2. Configure the environment variables in the docker-compose.yml to your choosing.<br />
   Note: *Your admin account will automatically be created based on the admin credentials in that file, so pay attention to those.*
3. Now start the container by running the following command in the same directory as your docker-compose.yml file. This will automatically setup the database and run the Khoj server.
   ```shell
   docker-compose up
   ```

Khoj should now be running at http://localhost:42110! You can see the web UI in your browser.

### 1B. Install Method 2: Pip

#### Prerequisites

##### Install Postgres (with PgVector)

Khoj uses Postgres DB for all server configuration and to scale to multi-user setups. It uses the pgvector package in Postgres to manage your document embeddings. Both Postgres and pgvector need to be installed for Khoj to work.

  <Tabs groupId="operating-systems" queryString="os">
    <TabItem value="macos" label="MacOS">
Install [Postgres.app](https://postgresapp.com/). This comes pre-installed with `pgvector` and relevant dependencies.
    </TabItem>
    <TabItem value="windows" label="Windows">
    For detailed instructions and troubleshooting, see [this section](/contributing/development#2-postgres-installation--setup).
    1. Use the [recommended installer](https://www.postgresql.org/download/windows/).
    2. Follow instructions to [Install PgVector](https://github.com/pgvector/pgvector#windows) in case you need to manually install it. Windows support is experimental for pgvector currently, so we recommend using Docker.
    </TabItem>
    <TabItem value="linux" label="Linux">
    From [official instructions](https://wiki.postgresql.org/wiki/Apt)
    </TabItem>
    <TabItem value="source" label="From Source">
    1. Follow instructions to [Install Postgres](https://www.postgresql.org/download/)
    2. Follow instructions to [Install PgVector](https://github.com/pgvector/pgvector#installation) in case you need to manually install it.
    </TabItem>
  </Tabs>

##### Create the Khoj database

Make sure to update your environment variables to match your Postgres configuration if you're using a different name. The default values should work for most people. When prompted for a password, you can use the default password `postgres`, or configure it to your preference. Make sure to set the environment variable `POSTGRES_PASSWORD` to the same value as the password you set here.

  <Tabs groupId="operating-systems" queryString="os">
    <TabItem value="macos" label="MacOS">
    ```shell
createdb khoj -U postgres --password
    ```
    </TabItem>
    <TabItem value="windows" label="Windows">
    ```shell
createdb -U postgres khoj --password
      ```
    </TabItem>
    <TabItem value="linux" label="Linux">
      ```shell
sudo -u postgres createdb khoj --password
      ```
    </TabItem>
  </Tabs>

#### Install Khoj server

##### Install Khoj Server
- *Make sure [python](https://realpython.com/installing-python/) and [pip](https://pip.pypa.io/en/stable/installation/) are installed on your machine*
- Check [llama-cpp-python setup](https://python.langchain.com/docs/integrations/llms/llamacpp#installation) if you hit any llama-cpp issues with the installation

Run the following command in your terminal to install the Khoj server.

  <Tabs groupId="operating-systems" queryString="os">
    <TabItem value="macos" label="MacOS">
    ```shell
# ARM/M1+ Machines
MAKE_ARGS="-DLLAMA_METAL=on" python -m pip install khoj

# Intel Machines
python -m pip install khoj
    ```
    </TabItem>
    <TabItem value="windows" label="Windows">
      In PowerShell on Windows
      ```shell
 # 1. (Optional) To use NVIDIA (CUDA) GPU
 $env:CMAKE_ARGS = "-DLLAMA_OPENBLAS=on"
 # 1. (Optional) To use AMD (ROCm) GPU
 $env:CMAKE_ARGS = "-DLLAMA_HIPBLAS=on"
 # 1. (Optional) To use VULCAN GPU
 $env:CMAKE_ARGS = "-DLLAMA_VULKAN=on"

 # 2. Install Khoj
 py -m pip install khoj
      ```
    </TabItem>
    <TabItem value="linux" label="Linux">
      ```shell
 # CPU
 python -m pip install khoj
 # NVIDIA (CUDA) GPU
 CMAKE_ARGS="DLLAMA_CUDA=on" FORCE_CMAKE=1 python -m pip install khoj
 # AMD (ROCm) GPU
 CMAKE_ARGS="-DLLAMA_HIPBLAS=on" FORCE_CMAKE=1 python -m pip install khoj
 # VULCAN GPU
 CMAKE_ARGS="-DLLAMA_VULKAN=on" FORCE_CMAKE=1 python -m pip install khoj
      ```
    </TabItem>
  </Tabs>

##### Start Khoj Server

Before getting started, configure the following environment variables in your terminal for the first run

  <Tabs groupId="operating-systems" queryString="os">
    <TabItem value="macos" label="MacOS">
      ```shell
      export KHOJ_ADMIN_EMAIL=<your-email>
      export KHOJ_ADMIN_PASSWORD=<your-password>
      ```
    </TabItem>
    <TabItem value="windows" label="Windows">
      If you're using PowerShell:
      ```shell
      $env:KHOJ_ADMIN_EMAIL="<your-email>"
      $env:KHOJ_ADMIN_PASSWORD="<your-password>"
      ```
    </TabItem>
    <TabItem value="linux" label="Linux">
      ```shell
      export KHOJ_ADMIN_EMAIL=<your-email>
      export KHOJ_ADMIN_PASSWORD=<your-password>
      ```
    </TabItem>
  </Tabs>


Run the following command from your terminal to start the Khoj backend and open Khoj in your browser.

```shell
khoj --anonymous-mode
```
`--anonymous-mode` allows you to run the server without setting up Google credentials for login. This allows you to use any of the clients without a login wall. If you want to use Google login, you can skip this flag, but you will have to add your Google developer credentials.

On the first run, you will be prompted to input credentials for your admin account and do some basic configuration for your chat model settings. Once created, you can go to http://localhost:42110/server/admin and login with the credentials you just created.

Khoj should now be running at http://localhost:42110. You can see the web UI in your browser.

Note: To start Khoj automatically in the background use [Task scheduler](https://www.windowscentral.com/how-create-automated-task-using-task-scheduler-windows-10) on Windows or [Cron](https://en.wikipedia.org/wiki/Cron) on Mac, Linux (e.g. with `@reboot khoj`)


### 2. Configure
#### Login to the Khoj Admin Panel
Go to http://localhost:42110/server/admin and login with the admin credentials you setup during installation.

:::info[CSRF Error]
Ensure you are using **localhost, not 127.0.0.1**, to access the admin panel to avoid the CSRF error.
:::

:::info[DISALLOWED HOST Error]
You may hit this if you try access Khoj exposed on a custom domain (e.g. 192.168.12.3 or example.com) or over HTTP.
Set the environment variables KHOJ_DOMAIN=your-domain and KHOJ_NO_HTTPS=false if required to avoid this error.
:::

:::tip[Note]
Using Safari on Mac? You might not be able to login to the admin panel. Try using Chrome or Firefox instead.
:::

#### Configure Chat Model
Setup which chat model you'd want to use. Khoj supports local and online chat models.

:::tip[Multiple Chat Models]
Add a `ServerChatSettings` with `Default` and `Summarizer` fields set to your preferred chat model via [the admin panel](http://localhost:42110/server/admin/database/serverchatsettings/add/). Otherwise Khoj defaults to use the first chat model in your [ChatModelOptions](http://localhost:42110/server/admin/database/chatmodeloptions/) for all non chat response generation tasks.
:::

##### Configure OpenAI Chat

:::info[Ollama Integration]
Using Ollama? See the [Ollama Integration](/advanced/ollama) section for more custom setup instructions.
:::

1. Go to the [OpenAI settings](http://localhost:42110/server/admin/database/openaiprocessorconversationconfig/) in the server admin settings to add an OpenAI processor conversation config. This is where you set your API key and server API base URL. The API base URL is optional - it's only relevant if you're using another OpenAI-compatible proxy server.

![example configuration for openai processor](/img/example_openai_processor_config.png)

2. Go over to configure your [chat model options](http://localhost:42110/server/admin/database/chatmodeloptions/). Set the `chat-model` field to a supported chat model[^1] of your choice. For example, you can specify `gpt-4o` if you're using OpenAI.
    - Make sure to set the `model-type` field to `OpenAI`.
    - The `tokenizer` and `max-prompt-size` fields are optional. Set them only if you're sure of the tokenizer or token limit for the model you're using. Contact us if you're unsure what to do here.
    - If your model supports vision, set the `vision enabled` field to `true`. This is currently only supported for OpenAI models with vision capabilities.

![example configuration for chat model options](/img/example_chatmodel_option.png)

##### Configure Anthropic Chat
1. Go to the [OpenAI settings](http://localhost:42110/server/admin/database/openaiprocessorconversationconfig/) in the server admin settings to add an OpenAI processor conversation config. This is kind of a misnomer, we know. Do not configure the API base url. Just add your API key and give the configuration a friendly name.
2. Go over to configure your [chat model options](http://localhost:42110/server/admin/database/chatmodeloptions/). Set the `chat-model` field to a supported chat model by Anthropic of your choice. For example, you can specify `claude-3-5-sonnet-20240620`.
    - Make sure to set the `model-type` field to `Anthropic`.
    - The `tokenizer` and `max-prompt-size` fields are optional. Set them only if you're sure of the tokenizer or token limit for the model you're using. Contact us if you're unsure what to do here.

##### Configure Offline Chat

Offline chat stays completely private and can work without internet using open-source models.

**System Requirements**:
- Minimum 8 GB RAM. Recommend **16Gb VRAM**
- Minimum **5 GB of Disk** available
- A CPU supporting [AVX or AVX2 instructions](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) is required
- An Nvidia, AMD GPU or a Mac M1+ machine would significantly speed up chat response times

Any chat model on Huggingface in GGUF format can be used for local chat. Here's how you can set it up:

1. No need to setup a conversation processor config!
2. Go over to configure your [chat model options](http://localhost:42110/server/admin/database/chatmodeloptions/). Set the `chat-model` field to a supported chat model[^1] of your choice. For example, we recommend `bartowski/Meta-Llama-3.1-8B-Instruct-GGUF`, but [any gguf model on huggingface](https://huggingface.co/models?library=gguf) should work.
  - Make sure to set the `model-type` to `Offline`. Do not set `openai config`.
  - The `tokenizer` and `max-prompt-size` fields are optional. You can set these for non-standard models (i.e not Mistral or Llama based models) or when you know the token limit of the model to improve context stuffing.

#### Share your data
You can sync your files and folders with Khoj using the [Desktop](/clients/desktop#setup), [Obsidian](/clients/obsidian#setup), or [Emacs](/clients/emacs#setup) clients or just drag and drop specific files on the [website](/clients/web#upload-documents). You can also directly sync your [Notion workspace](/data-sources/notion_integration).

[^1]: Khoj, by default, can use [OpenAI GPT3.5+ chat models](https://platform.openai.com/docs/models/overview) or [GGUF chat models](https://huggingface.co/models?library=gguf). See [this section](/advanced/use-openai-proxy) on how to locally use OpenAI-format compatible proxy servers.

### 3. Use Khoj 🚀

Now open http://localhost:42110 to start interacting with Khoj!

### 4. Install Khoj Clients (Optional)
Khoj exposes a web interface to search, chat and configure by default.<br />
You can install a Khoj client to sync your documents or to easily access Khoj from within Obsidian, Emacs or your OS.

- **Khoj Desktop**:<br />
[Install](/clients/desktop#setup) the Khoj Desktop app.

- **Khoj Obsidian**:<br />
[Install](/clients/obsidian#setup) the Khoj Obsidian plugin.

- **Khoj Emacs**:<br />
[Install](/clients/emacs#setup) khoj.el

#### Setup host URL
Set the host URL on your clients settings page to your Khoj server URL. By default, use `http://127.0.0.1:42110` or `http://localhost:42110`. Note that `localhost` may not work in all cases.

## Upgrade

  <Tabs groupId="environment">
    <TabItem value="localsetup" label="Local Setup">
      ```shell
      pip install --upgrade khoj
      ```
      *Note: To upgrade to the latest pre-release version of the khoj server run below command*
    </TabItem>
    <TabItem value="docker" label="Docker">
      From the same directory where you have your `docker-compose` file, this will fetch the latest build and upgrade your server.
      ```shell
      docker-compose up --build
      ```
    </TabItem>
    <TabItem value="emacs" label="Emacs">
    - Use your Emacs Package Manager to Upgrade
    - See [khoj.el package setup](/clients/emacs#setup) for details
    </TabItem>
    <TabItem value="obsidian" label="Obsidian">
      - Upgrade via the Community plugins tab on the settings pane in the Obsidian app
      - See the [khoj plugin setup](/clients/obsidian#setup) for details
    </TabItem>
  </Tabs>

## Uninstall

  <Tabs groupId="environment">
    <TabItem value="localsetup" label="Local Setup">
    ```shell
    # uninstall khoj server
    pip uninstall khoj

    # delete khoj postgres db
    dropdb khoj -U postgres
    ```
    </TabItem>
    <TabItem value="docker" label="Docker">
    From the same directory where you have your `docker-compose` file, run the command below to remove the server to delete its containers, networks, images and volumes.

    ```shell
    docker-compose down --volumes
    ```
    </TabItem>
    <TabItem value="emacs" label="Emacs">
    Uninstall the khoj Emacs, or desktop client in the standard way from Emacs or your OS respectively
    You can also `rm -rf ~/.khoj` to remove the Khoj data directory if did a local install.
    </TabItem>
    <TabItem value="obsidian" label="Obsidian">
    Uninstall the khoj Obisidan, or desktop client in the standard way from Obsidian or your OS respectively
    You can also `rm -rf ~/.khoj` to remove the Khoj data directory if did a local install.
    </TabItem>
  </Tabs>

## Troubleshoot

#### Dependency conflict when trying to install Khoj python package with pip
- **Reason**: When conflicting dependency versions are required by Khoj vs other python packages installed on your system
- **Fix**: Install Khoj in a python virtual environment using [venv](https://docs.python.org/3/library/venv.html) or [pipx](https://pypa.github.io/pipx) to avoid this dependency conflicts
- **Process**:
  1. Install [pipx](https://pypa.github.io/pipx/#install-pipx)
  2. Use `pipx` to install Khoj to avoid dependency conflicts with other python packages.
     ```shell
     pipx install khoj
     ```
  3. Now start `khoj` using the standard steps described earlier


#### Install fails while building Tokenizer dependency
- **Details**: `pip install khoj` fails while building the `tokenizers` dependency. Complains about Rust.
- **Fix**: Install Rust to build the tokenizers package. For example on Mac run:
    ```shell
    brew install rustup
    rustup-init
    source ~/.cargo/env
    ```
- **Refer**: [Issue with Fix](https://github.com/khoj-ai/khoj/issues/82#issuecomment-1241890946) for more details


#### Khoj in Docker errors out with \"Killed\" in error message
- **Fix**: Increase RAM available to Docker Containers in Docker Settings
- **Refer**: [StackOverflow Solution](https://stackoverflow.com/a/50770267), [Configure Resources on Docker for Mac](https://docs.docker.com/desktop/mac/#resources)

## Advanced
### Self Host on Custom Domain

You can self-host Khoj behind a custom domain as well. To do so, you need to set the `KHOJ_DOMAIN` environment variable to your domain (e.g., `export KHOJ_DOMAIN=my-khoj-domain.com` or add it to your `docker-compose.yml`). By default, the Khoj server you set up will not be accessible outside of `localhost` or `127.0.0.1`.

:::warning[Without HTTPS certificate]
To expose Khoj on a custom domain over the public internet, use of an SSL certificate is strongly recommended. You can use [Let's Encrypt](https://letsencrypt.org/) to get a free SSL certificate for your domain.

To disable HTTPS, set the `KHOJ_NO_HTTPS` environment variable to `True`. This can be useful if Khoj is only accessible behind a secure, private network.
:::