---
description: >-
  This page contains a detailed process for building and running Sentient from
  the source code on our GitHub repo.
---

# Running Sentient from Source (Self-Host)

## Self-Hosting Sentient with Docker: A Complete Guide

Welcome! This guide will walk you through setting up and running your own private instance of Sentient using Docker. The process is designed to be as simple as possible, boiling down to two main steps: configuring your environment and running a single command.

This self-hosted setup is special because it **does not require Auth0 for authentication**. Instead, it uses a secure, static token that you generate, ensuring your instance is completely independent and private.

### Prerequisites

Before you begin, please ensure you have the following installed and running on your system:

* **Docker and Docker Compose:**
  * **Windows:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) is required. Make sure it's configured to use the **WSL 2 backend**, which is the default for modern installations.
  * **Linux:** Install [Docker Engine](https://docs.docker.com/engine/install/) and the [Docker Compose Plugin](https://docs.docker.com/compose/install/).
* **Git:** Required for cloning the project repository.
* **A Code Editor:** A good editor like [VS Code](https://code.visualstudio.com/) will make editing configuration files easier.

### Step 1: Configure Your Environment

This is the most important step. You will create three environment files by copying and editing the provided templates. These files control everything from your login token to API keys for various features.

All paths are relative to the `src` directory inside the project you cloned.

#### 1.1. Root Environment (`src/.env`)

This file is the master configuration for Docker Compose. It defines your database credentials, your private authentication token, and the public URL for the application.

1. Navigate to the `src` directory.
2. Copy the template file `src/.env.selfhost.template` and rename the copy to `src/.env`.
3. Open the new `src/.env` file and edit the placeholders:

> **File: `src/.env`**
>
> ```env
> # Root environment variables for docker-compose.yml (self-hosting)
> # This file provides credentials to Docker Compose and build-time args for the client.
>
> # --- Client Build-Time Variables ---
> # This URL is what your BROWSER uses. Do not change it.
> NEXT_PUBLIC_APP_SERVER_URL=http://localhost:5000
>
> # This sets the application to run in self-hosted mode. Do not change it.
> NEXT_PUBLIC_ENVIRONMENT=SELFHOST
>
> # This should be a long, random, secret string. It acts as your master password.
> # Generate a strong secret here. You can use a password manager or an online tool.
> SELF_HOST_AUTH_TOKEN=<generate_a_strong_secret_here>
>
> # --- Database Credentials ---
> # You can leave these as default or set your own secure passwords.
> MONGO_USER=sentient
> MONGO_PASS=<generate_a_strong_password_for_mongo>
>
> # --- Redis Password ---
> # You can leave this as default or set your own secure password.
> REDIS_PASSWORD=<generate_a_strong_password_for_redis>
> ```

**Action:** Replace `<generate_a_strong_secret_here>` and the password placeholders with your own secure, random values. **Remember the `SELF_HOST_AUTH_TOKEN` value; you will need it in the next step.**

#### 1.2. Client Environment (`src/client/.env.selfhost`)

This file provides runtime environment variables specifically for the Next.js client container.

1. Navigate to the `src/client` directory.
2. Copy `src/client/.env.selfhost.template` and rename the copy to `src/client/.env.selfhost`.
3. Open the new file and edit the `SELF_HOST_AUTH_TOKEN` value.

> **File: `src/client/.env.selfhost`**
>
> ```env
> # Environment variables for the client in SELFHOST mode.
> # This file is loaded at runtime by the client container.
>
> # Set the environment to self-host mode
> NEXT_PUBLIC_ENVIRONMENT=SELFHOST
>
> # The URL for the backend server, accessible from the user's browser.
> # This should match the value in the root .env file.
> NEXT_PUBLIC_APP_SERVER_URL=http://localhost:5000
>
> # The internal URL for the backend server, used for server-to-server communication inside Docker.
> # It MUST use the Docker service name ('server') and the internal port (80).
> INTERNAL_APP_SERVER_URL=http://server:80
>
> # The static token for authenticating with the backend.
> # This MUST match the `SELF_HOST_AUTH_TOKEN` in the root .env file.
> SELF_HOST_AUTH_TOKEN=<use_the_same_strong_secret_as_in_the_root_env>
>
> # Auth0 variables are not used in SELFHOST mode, but are kept here
> # to avoid breaking any code that might reference them before a check.
> # The build process requires them to be present in some form.
> AUTH0_SECRET=""
> AUTH0_BASE_URL="http://localhost:3000"
> AUTH0_ISSUER_BASE_URL=""
> AUTH0_CLIENT_ID=""
> AUTH0_CLIENT_SECRET=""
> AUTH0_AUDIENCE=""
> AUTH0_SCOPE=""
> ```

**Action:** Replace `<use_the_same_strong_secret_as_in_the_root_env>` with the **exact same token** you generated for `SELF_HOST_AUTH_TOKEN` in `src/.env`.

#### 1.3. Server Environment (`src/server/.env.selfhost`)

This file configures the Python backend, including its database connections and optional API keys for third-party services.

1. Navigate to the `src/server` directory.
2. Copy `src/server/.env.selfhost.template` and rename the copy to `src/server/.env.selfhost`.
3. Open the new file and edit the required and optional values.

> **File: `src/server/.env.selfhost`**
>
> ```env
> # Environment variables for the server in SELFHOST mode.
> # This file is loaded at runtime by the server container.
>
> # --- Environment ---
> ENVIRONMENT=SELFHOST
>
> # --- Self-Host Authentication ---
> # This MUST match the `SELF_HOST_AUTH_TOKEN` in the client's .env.selfhost file.
> SELF_HOST_AUTH_SECRET=<use_the_same_strong_secret_as_in_the_root_env>
>
> # --- Auth0 Dummy Configuration (Permissions are still derived from this scope) ---
> AUTH0_SCOPE='openid profile email offline_access read:chat write:chat read:profile write:profile manage:google_auth read:tasks write:tasks read:notifications read:config write:config admin:user_metadata read:journal write:journal'
>
> # --- Database (points to the Docker service) ---
> # These values are automatically substituted by Docker Compose from your root .env file.
> # DO NOT CHANGE THESE LINES.
> MONGO_URI=mongodb://${MONGO_USER}:${MONGO_PASS}@mongodb:27017/
> MONGO_DB_NAME=sentient_selfhost_db
>
> # --- Task Queue (Celery, points to the Docker service) ---
> # This value is also automatically substituted by Docker Compose.
> # DO NOT CHANGE THIS LINE.
> CELERY_BROKER_URL=redis://:${REDIS_PASSWORD}@redis:6379/0
> CELERY_RESULT_BACKEND=redis://:${REDIS_PASSWORD}@redis:6379/0
>
> # --- 3rd Party API Keys (Optional but recommended for full functionality) ---
> UNSPLASH_ACCESS_KEY=<your_unsplash_access_key>
> NEWS_API_KEY=<your_news-api-key>
> GOOGLE_API_KEY=<your-google-cloud-api-key>
> GOOGLE_CSE_ID=<your-google-custom-search-engine-id>
> GEMINI_API_KEY=<your-gemini-api-key>
>
> # --- Encryption ---
> # Generate two long, random hexadecimal strings for these values.
> # Example: openssl rand -hex 32
> AES_SECRET_KEY=<generate_a_64_char_hex_string>
> AES_IV=<generate_a_32_char_hex_string>
>
> # --- MCP Hub Internal URLs (for services running inside the container via supervisord) ---
> # These are for internal communication and should NOT be changed.
> GMAIL_MCP_SERVER_URL=http://localhost:9001/sse
> # ... (rest of the MCP URLs) ...
> ```

**Actions:**

1. **`SELF_HOST_AUTH_SECRET`:** Paste the **exact same token** you've used in the other files.
2. **`AES_SECRET_KEY` & `AES_IV`:** Replace the placeholders with new, randomly generated hexadecimal strings. You can use an online generator or a command-line tool like `openssl rand -hex 32` (for the key) and `openssl rand -hex 16` (for the IV).
3. **Optional API Keys:** To enable all features, you'll need to get API keys from these services:

| Variable              | Service          | Link                                                                       | Purpose                                                    |
| --------------------- | ---------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `UNSPLASH_ACCESS_KEY` | Unsplash         | [Unsplash Developers](https://unsplash.com/developers)                     | Used by the GDocs/GSlides agents to find images.           |
| `NEWS_API_KEY`        | NewsAPI.org      | [NewsAPI.org](https://newsapi.org/)                                        | Enables the News tool for fetching headlines.              |
| `GOOGLE_API_KEY`      | Google Cloud     | [Google Cloud Console](https://console.cloud.google.com/apis/credentials)  | For Google Search, Maps, and Shopping tools.               |
| `GOOGLE_CSE_ID`       | Google Search    | [Programmable Search Engine](https://programmablesearchengine.google.com/) | The ID for your custom search engine.                      |
| `GEMINI_API_KEY`      | Google AI Studio | [Google AI for Developers](https://ai.google.dev/)                         | Powers semantic search in the Gmail tool.                  |
| `NOVITA_API_KEY`      | Novita           | [Novita AI Console](https://novita.ai/console)                             | Novita AI provides the Qwen3:4B model completely for free. |

{% hint style="info" %}
We use Novita as our provider, but you can use any OpenAI API endpoint you want. We don't have a dynamic base URL setup yet, but this can be added very easily. Novita AI's API uses the OpenAI API standard, so if you want to use a different provider today, all you have to do is change the base URL everywhere in the app and set your API key in the NOVITA\_API\_KEY env variable.
{% endhint %}

### Step 2: Build and Run the Application

Once your environment files are configured, starting the application is a single command.

1. Open your terminal and navigate to the `src` directory of the project.
2.  Run the following command:

    ```bash
    docker compose up --build -d
    ```

* `--build`: This tells Docker to build the images from the Dockerfiles the first time you run it, or if any code has changed.
* `-d`: This runs the containers in "detached" mode, meaning they will run in the background.

The initial build may take several minutes. Once it's complete, all services (Client, Server, Database, Redis) will be running.

### Accessing Your Sentient Instance

That's it! You can now access your private Sentient instance by navigating to:

[**http://localhost:3000**](http://localhost:3000)

### Managing Your Self-Hosted Instance

Here are some useful Docker commands to manage your running application. Run these from the `src` directory.

*   **View Logs:** To see the live logs from the client or server container, use:

    ```bash
    # View backend server logs
    docker compose logs -f sentient-server-selfhost

    # View frontend client logs
    docker compose logs -f sentient-client-selfhost
    ```
*   **Stop the Application:** To stop all the running containers:

    ```bash
    docker compose down
    ```
*   **Stop and Delete All Data:** If you want to stop the application and completely wipe the database and Redis cache (for a clean restart), use the `-v` flag. **Warning:** This is irreversible.

    ```bash
    docker compose down -v
    ```
