# 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. The default configuration uses a local LLM (Ollama) for chat, so you can get started without any external AI service API keys. #### Prerequisites Before you begin, please ensure you have the following installed and running on your system: * **Docker and Docker Compose:** * **Windows/Mac:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) is required. For Windows, make sure it's configured to use the **WSL 2 backend**. * **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 build-time configuration for the services. 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. See the updated template below for guidance. **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 placeholders, ensuring they match the values from your root `src/.env` file. **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. #### 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 -f docker-compose.selfhost.yml up --build -d ``` * `-f docker-compose.selfhost.yml`: Explicitly tells Docker to use the self-hosting configuration. * `--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 as it downloads dependencies and the local LLM. Once it's complete, all services (Client, Server, Databases, etc.) will be running. #### Step 3: 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 any container, use: ````bash # View backend server logs (most common) docker compose -f docker-compose.selfhost.yml logs -f server # View frontend client logs docker compose -f docker-compose.selfhost.yml logs -f client ```* **Stop the Application:** To stop all the running containers: ```bash docker compose -f docker-compose.selfhost.yml down ```` * **Stop and Delete All Data:** If you want to stop the application and completely wipe the database volumes (for a clean restart), use the `-v` flag. **Warning:** This is irreversible. ```bash docker compose -f docker-compose.selfhost.yml down -v ``` #### Appendix: LLM Configuration The default self-host setup uses **Ollama** to run a local LLM, so you don't need any external API keys for basic chat functionality. However, for memory and other features, you'll need a **Gemini API Key**. You can also configure Sentient to use a different LLM provider: * **Using Gemini for Chat:** 1. Get a `GEMINI_API_KEY` and add it to your `src/.env` file. 2. In `src/server/.env.selfhost`, change `OPENAI_API_BASE_URL` to `http://litellm:4000`. 3. In `src/server/.env.selfhost`, change `OPENAI_MODEL_NAME` to `gemini-1.5-flash`. 4. Restart your application: `docker compose -f docker-compose.selfhost.yml up --build -d`. * **Using other OpenAI-compatible services (e.g., Groq, TogetherAI):** 1. In `src/.env`, change `OPENAI_API_KEY` from `ollama` to your actual API key. 2. In `src/server/.env.selfhost`, change `OPENAI_API_BASE_URL` to the service's endpoint URL and `OPENAI_MODEL_NAME` to the desired model. 3. Restart your application. #### Appendix: Optional API Keys To unlock all of Sentient's capabilities, you'll need to provide API keys for various third-party services in the `src/server/.env.selfhost` file. | Variable | Service | Link | Purpose | | --------------------- | ---------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `GEMINI_API_KEY` | Google AI Studio | [ai.google.dev](https://ai.google.dev/) | **(Highly Recommended)** Powers memory embeddings and can be used for chat via LiteLLM. | | `DEEPGRAM_API_KEY` | Deepgram | [deepgram.com](https://deepgram.com/) | **(Optional)** For high-quality speech-to-text in Voice Mode. | | `ELEVENLABS_API_KEY` | ElevenLabs | [elevenlabs.io](https://elevenlabs.io/) | **(Optional)** For high-quality text-to-speech in Voice Mode. | | `SMALLEST_AI_API_KEY` | Smallest AI | [smallest.ai](https://smallest.ai/) | **(Optional)** An alternative provider for text-to-speech. | | `HF_TOKEN` | Hugging Face | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) | **(Optional)** Required for WebRTC voice connections if not on localhost. | | `COMPOSIO_API_KEY` | Composio | [composio.dev](https://composio.dev/) | **(Optional)** A tool aggregator that simplifies connecting to Google services like Gmail, Calendar, and Drive. | | `GOOGLE_API_KEY` | Google Cloud | [console.cloud.google.com](https://console.cloud.google.com/apis/credentials) | **(Optional)** For Google Search and Maps tools. | | `GOOGLE_CSE_ID` | Google Search | [programmablesearchengine.google.com](https://programmablesearchengine.google.com/) | **(Optional)** The ID for your custom search engine. | | `NEWS_API_KEY` | NewsAPI.org | [newsapi.org](https://newsapi.org/) | **(Optional)** Enables the News tool for fetching headlines. | | `ACCUWEATHER_API_KEY` | AccuWeather | [developer.accuweather.com](https://developer.accuweather.com/) | **(Optional)** Enables the Weather tool. | | `UNSPLASH_ACCESS_KEY` | Unsplash | [unsplash.com/developers](https://unsplash.com/developers) | **(Optional)** Used by agents to find images for presentations. | | `GITHUB_CLIENT_ID` | GitHub | [github.com/settings/developers](https://github.com/settings/developers) | **(Optional)** For connecting your GitHub account. | | `SLACK_CLIENT_ID` | Slack | [api.slack.com/apps](https://api.slack.com/apps) | **(Optional)** For connecting your Slack workspace. | | `NOTION_CLIENT_ID` | Notion | [notion.so/my-integrations](https://www.notion.so/my-integrations) | **(Optional)** For connecting your Notion workspace. | | `DISCORD_CLIENT_ID` | Discord | [discord.com/developers/applications](https://discord.com/developers/applications) | **(Optional)** For connecting your Discord account. | | `TRELLO_CLIENT_ID` | Trello | [trello.com/power-ups/admin](https://trello.com/power-ups/admin) | **(Optional)** For connecting your Trello account. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://sentient-2.gitbook.io/docs/getting-started/running-sentient-from-source-self-host.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.