Running Sentient from Source (Self-Host)

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

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 is required. Make sure it's configured to use the WSL 2 backend, which is the default for modern installations.

  • Linux: Install Docker Engine and the Docker Compose Plugin.

• Git: Required for cloning the project repository.

• A Code Editor: A good editor like VS Code 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

# 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

# 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

# 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	Used by the GDocs/GSlides agents to find images.
NEWS_API_KEY	NewsAPI.org	NewsAPI.org	Enables the News tool for fetching headlines.
GOOGLE_API_KEY	Google Cloud	Google Cloud Console	For Google Search, Maps, and Shopping tools.
GOOGLE_CSE_ID	Google Search	Programmable Search Engine	The ID for your custom search engine.
GEMINI_API_KEY	Google AI Studio	Google AI for Developers	Powers semantic search in the Gmail tool.
NOVITA_API_KEY	Novita	Novita AI Console	Novita AI provides the Qwen3:4B model completely for free.

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.

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:

   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

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:

  # 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:

  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.

  docker compose down -v