arc53--docsgpt/docs/content/Deploying/DocsGPT-Settings.mdx

---
title: DocsGPT Settings
description: Configure your DocsGPT application by understanding the basic settings.
---

import { Callout } from 'nextra/components'

# DocsGPT Settings

DocsGPT is highly configurable, allowing you to tailor it to your specific needs and preferences. You can control various aspects of the application, from choosing the Large Language Model (LLM) provider to selecting embedding models and vector stores.

This document will guide you through the basic settings you can configure in DocsGPT. These settings determine how DocsGPT interacts with LLMs and processes your data.

## Configuration Methods

There are two primary ways to configure DocsGPT settings:

### 1. Configuration via `.env` file (Recommended)

The easiest and recommended way to configure basic settings is by using a `.env` file. This file should be located in the **root directory** of your DocsGPT project (the same directory where `setup.sh` is located).

**Example `.env` file structure:**

```
LLM_PROVIDER=openai
API_KEY=YOUR_OPENAI_API_KEY
LLM_NAME=gpt-4o
```

### 2. Configuration via `settings.py` file (Advanced)

For more advanced configurations or if you prefer to manage settings directly in code, you can modify the `settings.py` file. This file is located in the `application/core` directory of your DocsGPT project.

While modifying `settings.py` offers more flexibility, it's generally recommended to use the `.env` file for basic settings and reserve `settings.py` for more complex adjustments or when you need to configure settings programmatically.

**Location of `settings.py`:** `application/core/settings.py`

## Basic Settings Explained

Here are some of the most fundamental settings you'll likely want to configure:

- **`LLM_PROVIDER`**: This setting determines which Large Language Model (LLM) provider DocsGPT will use. It tells DocsGPT which API to interact with.

  - **Common values:**
    - `docsgpt`: Use the DocsGPT Public API Endpoint (simple and free, as offered in `setup.sh` option 1).
    - `openai`: Use OpenAI's API (requires an API key).
    - `google`: Use Google's Vertex AI or Gemini models.
    - `anthropic`: Use Anthropic's Claude models.
    - `groq`: Use Groq's models.
    - `huggingface`: Use HuggingFace Inference API.
    - `openai` (when using local inference engines like Ollama, Llama.cpp, TGI, etc.): This signals DocsGPT to use an OpenAI-compatible API format, even if the actual LLM is running locally.

- **`LLM_NAME`**: Specifies the specific model to use from the chosen LLM provider. The available models depend on the `LLM_PROVIDER` you've selected.

  - **Examples:**
    - For `LLM_PROVIDER=openai`: `gpt-4o`
    - For `LLM_PROVIDER=google`: `gemini-3.5-flash`
    - For local models (e.g., Ollama): `llama3.2:1b` (or any model name available in your setup).

- **`EMBEDDINGS_NAME`**: This setting defines which embedding model DocsGPT will use to generate vector embeddings for your documents. Embeddings are numerical representations of text that allow DocsGPT to understand the semantic meaning of your documents for efficient search and retrieval.

  - **Default value:** `huggingface_sentence-transformers/all-mpnet-base-v2` (a good general-purpose embedding model).
  - **Other options:** You can explore other embedding models from Hugging Face Sentence Transformers or other providers if needed.

- **`API_KEY`**: Required for most cloud-based LLM providers. This is your authentication key to access the LLM provider's API. You'll need to obtain this key from your chosen provider's platform.

- **`OPENAI_BASE_URL`**: Specifically used when `LLM_PROVIDER` is set to `openai` but you are connecting to a local inference engine (like Ollama, Llama.cpp, etc.) that exposes an OpenAI-compatible API. This setting tells DocsGPT where to find your local LLM server.

- **`STT_PROVIDER`**: Selects the speech-to-text provider used for microphone transcription in chat and for audio file ingestion through the parser pipeline.

## Configuration Examples

Let's look at some concrete examples of how to configure these settings in your `.env` file.

### Example for Cloud API Provider (OpenAI)

To use OpenAI's `gpt-4o` model, you would configure your `.env` file like this:

```
LLM_PROVIDER=openai
API_KEY=YOUR_OPENAI_API_KEY  # Replace with your actual OpenAI API key
LLM_NAME=gpt-4o
```

Make sure to replace `YOUR_OPENAI_API_KEY` with your actual OpenAI API key.

### Example for Local Deployment

To use a local Ollama server with the `llama3.2:1b` model, you would configure your `.env` file like this:

```
LLM_PROVIDER=openai # Using OpenAI compatible API format for local models
API_KEY=None      # API Key is not needed for local Ollama
LLM_NAME=llama3.2:1b
OPENAI_BASE_URL=http://host.docker.internal:11434/v1 # Default Ollama API URL within Docker
EMBEDDINGS_NAME=huggingface_sentence-transformers/all-mpnet-base-v2 # You can also run embeddings locally if needed
```

In this case, even though you are using Ollama locally, `LLM_PROVIDER` is set to `openai` because Ollama (and many other local inference engines) are designed to be API-compatible with OpenAI. `OPENAI_BASE_URL` points DocsGPT to the local Ollama server.

## Adding Custom Models (`MODELS_CONFIG_DIR`)

DocsGPT ships with a built-in catalog of models for the providers it
supports out of the box (OpenAI, Anthropic, Google, Groq, OpenRouter,
Novita, Hugging Face, DocsGPT). To add **your own
models** without forking the repo — for example, a Mistral or Together
account, a self-hosted vLLM endpoint, or any other OpenAI-compatible
API — point `MODELS_CONFIG_DIR` at a directory of YAML files.

```
MODELS_CONFIG_DIR=/etc/docsgpt/models
MISTRAL_API_KEY=sk-...
```

A minimal YAML for one provider:

```yaml
# /etc/docsgpt/models/mistral.yaml
provider: openai_compatible
display_provider: mistral
api_key_env: MISTRAL_API_KEY
base_url: https://api.mistral.ai/v1
defaults:
  supports_tools: true
  context_window: 128000
models:
  - id: mistral-large-latest
    display_name: Mistral Large
  - id: mistral-small-latest
    display_name: Mistral Small
```

After restart, those models appear in `/api/models` and are selectable
in the UI. A working template lives at
`application/core/models/examples/mistral.yaml.example`.

**What you can do:**

- Add new `openai_compatible` providers (Mistral, Together, Fireworks,
  Ollama, vLLM, ...) — one YAML per provider, each with its own
  `api_key_env` and `base_url`.
- Extend an existing provider's catalog by dropping a YAML with the
  same `provider:` value as the built-in (e.g. `provider: anthropic`
  with extra models).
- Override a built-in model's capabilities by re-declaring the same
  `id` — later wins, override is logged at `WARNING`.

**What you cannot do via `MODELS_CONFIG_DIR`:** add a brand-new
non-OpenAI provider. That requires a Python plugin under
`application/llm/providers/`. See
`application/core/models/README.md` for the full schema reference.

### Docker

Mount the directory and set the env var:

```yaml
# docker-compose.yml
services:
  app:
    image: arc53/docsgpt
    environment:
      MODELS_CONFIG_DIR: /etc/docsgpt/models
      MISTRAL_API_KEY: ${MISTRAL_API_KEY}
    volumes:
      - ./my-models:/etc/docsgpt/models:ro
```

### Misconfiguration

If `MODELS_CONFIG_DIR` is set but the path doesn't exist (or isn't a
directory), the app logs a `WARNING` at boot and continues with just
the built-in catalog — it does **not** fail to start. If a YAML
declares an unknown provider name or has a schema error, the app
**does** fail to start, with the offending file path in the message.

## Speech-to-Text Settings

DocsGPT can transcribe audio in two places:

- Voice input in the chat.
- Audio file ingestion. Uploaded `.wav`, `.mp3`, `.m4a`, `.ogg`, and `.webm` files are transcribed first and then passed through the normal parser, chunking, embedding, and indexing pipeline.

The settings below control speech-to-text behaviour for both voice input and audio file ingestion.

| Setting | Purpose | Typical values |
| --- | --- | --- |
| `STT_PROVIDER` | Speech-to-text backend provider. | `openai`, `faster_whisper` |
| `OPENAI_STT_MODEL` | OpenAI transcription model used when `STT_PROVIDER=openai`. | `gpt-4o-mini-transcribe` |
| `STT_LANGUAGE` | Optional language hint passed to the provider. Leave unset for auto-detection when supported. | `en`, `es`, unset |
| `STT_MAX_FILE_SIZE_MB` | Maximum file size accepted by the synchronous `/api/stt` endpoint. | `50` |
| `STT_ENABLE_TIMESTAMPS` | Include timestamp segments in the normalized transcript response and stored parser metadata. | `true`, `false` |
| `STT_ENABLE_DIARIZATION` | Reserved provider option for speaker diarization. Some providers may ignore it. | `true`, `false` |

### Example: OpenAI Speech-to-Text

```env
STT_PROVIDER=openai
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
OPENAI_STT_MODEL=gpt-4o-mini-transcribe
STT_LANGUAGE=
STT_MAX_FILE_SIZE_MB=50
STT_ENABLE_TIMESTAMPS=false
STT_ENABLE_DIARIZATION=false
```

If you already use `API_KEY` for OpenAI, DocsGPT can reuse that key for transcription. Set `OPENAI_API_KEY` only when you want a dedicated key.

### Example: Local `faster_whisper`

```env
STT_PROVIDER=faster_whisper
STT_LANGUAGE=en
STT_ENABLE_TIMESTAMPS=true
STT_ENABLE_DIARIZATION=false
```

`faster_whisper` is an optional backend dependency. Install it in the Python environment used by the DocsGPT API and worker before selecting this provider.

## Authentication Settings

DocsGPT includes a JWT (JSON Web Token) based authentication feature for managing sessions or securing local deployments while allowing access.

### `AUTH_TYPE` Overview

The `AUTH_TYPE` setting in your `.env` file or `settings.py` determines the authentication method used by DocsGPT. This allows you to control how users authenticate with your DocsGPT instance.

| Value         | Description                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------- |
| `None`        | No authentication is used. Anyone can access the app.                                       |
| `simple_jwt`  | A single, long-lived JWT token is generated at startup. All requests use this shared token. |
| `session_jwt` | Unique JWT tokens are generated for each session/user.                                      |
| `oidc`        | Users sign in through an external OpenID Connect provider (Authentik, Keycloak, Okta, ...). See [SSO with OIDC](/Deploying/OIDC-SSO). |

#### How to Configure

Add the following to your `.env` file (or set in `settings.py`):

```env
# No authentication (default)
AUTH_TYPE=None

# OR: Simple JWT (shared token)
AUTH_TYPE=simple_jwt
JWT_SECRET_KEY=your_secret_key_here

# OR: Session JWT (per-user/session tokens)
AUTH_TYPE=session_jwt
JWT_SECRET_KEY=your_secret_key_here

# OR: SSO via an OpenID Connect provider (Authentik, Keycloak, Okta, ...)
AUTH_TYPE=oidc
OIDC_ISSUER=https://auth.example.com/application/o/docsgpt/
OIDC_CLIENT_ID=your_client_id
OIDC_FRONTEND_URL=https://docsgpt.example.com
JWT_SECRET_KEY=your_secret_key_here
```

- If `AUTH_TYPE` is set to `simple_jwt` or `session_jwt`, a `JWT_SECRET_KEY` is required.
- If `JWT_SECRET_KEY` is not set, DocsGPT will generate one and store it in `.jwt_secret_key` in the project root.

#### How Each Method Works

- **None**: No authentication. All API and UI access is open.
- **simple_jwt**:
  - A single JWT token is generated at startup and printed to the console.
  - Use this token in the `Authorization` header for all API requests:
    ```http
    Authorization: Bearer <SIMPLE_JWT_TOKEN>
    ```
  - The frontend will prompt for this token if not already set.
- **session_jwt**:
  - Clients can request a new token from `/api/generate_token`.
  - Use the received token in the `Authorization` header for subsequent requests.
  - Each user/session gets a unique token.
- **oidc**:
  - The frontend redirects users to your identity provider to sign in (OAuth2 Authorization Code + PKCE).
  - After a successful sign-in, DocsGPT issues its own session JWT; API requests carry it in the `Authorization` header like the other modes.
  - Stable per-user identities come from the provider — see the full setup guide: [SSO with OIDC](/Deploying/OIDC-SSO).
  - The same guide covers the optional access controls: group allowlists, silent session renewal, back-channel logout, SCIM provisioning, and login auditing.

#### Security Notes

- Always keep your `JWT_SECRET_KEY` secure and private.
- If you set it manually, use a strong, random string.
- If not set, DocsGPT will generate a secure key and persist it in `.jwt_secret_key`.

#### Checking Current Auth Type

- Use the `/api/config` endpoint to check the current `auth_type` and whether authentication is required.

#### Frontend Token Input for `simple_jwt`

If you have configured `AUTH_TYPE=simple_jwt`, the DocsGPT frontend will prompt you to enter the JWT token if it's not already set or is invalid. Paste the `SIMPLE_JWT_TOKEN` (printed to your console when the backend starts) into this field to access the application.

<img
  src="/jwt-input.png"
  alt="Frontend prompt for JWT Token"
  style={{
    width: "500px",
    maxWidth: "100%",
    display: "block",
    margin: "1em auto",
  }}
/>

## S3 Storage Backend

By default DocsGPT stores files locally. Set `STORAGE_TYPE=s3` to use Amazon S3 — or any S3-compatible service (MinIO, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, …) — instead.

| Setting | Description | Default |
| --- | --- | --- |
| `STORAGE_TYPE` | `local` or `s3` | `local` |
| `S3_BUCKET_NAME` | Bucket name | `docsgpt-test-bucket` |
| `S3_ACCESS_KEY_ID` | Access key ID | — |
| `S3_SECRET_ACCESS_KEY` | Secret access key | — |
| `S3_REGION` | Region (use `auto` for Cloudflare R2) | — |
| `S3_ENDPOINT_URL` | Custom endpoint for S3-compatible services; leave unset for AWS S3 | — |
| `S3_PATH_STYLE` | Use path-style addressing (required by most non-AWS services) | `false` |
| `URL_STRATEGY` | `backend` (proxy through API) or `s3` (direct object URLs) | `backend` |

### AWS S3

```env
STORAGE_TYPE=s3
S3_BUCKET_NAME=your-bucket-name
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
S3_REGION=us-east-1
```

### S3-compatible services (MinIO, Cloudflare R2, …)

Set `S3_ENDPOINT_URL` and usually `S3_PATH_STYLE=true`:

```env
STORAGE_TYPE=s3
S3_BUCKET_NAME=your-bucket-name
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
S3_REGION=auto
S3_ENDPOINT_URL=https://<account>.r2.cloudflarestorage.com
S3_PATH_STYLE=true
```

Your credentials need these permissions on the bucket: `s3:PutObject`, `s3:GetObject`, `s3:DeleteObject`, `s3:ListBucket`, `s3:HeadObject`.

> **Deprecated:** earlier versions reused the `SAGEMAKER_ACCESS_KEY`, `SAGEMAKER_SECRET_KEY`, and `SAGEMAKER_REGION` variables for S3 credentials. These are still honored as a fallback (with a deprecation warning) but you should migrate to the `S3_*` variables above.

## User-Data Storage (Postgres)

DocsGPT stores user data — conversations, agents, prompts, sources, attachments, workflows, logs, and token usage — in **PostgreSQL**. The backend connects via a single setting:

| Setting | Description | Default |
| --- | --- | --- |
| `POSTGRES_URI` | SQLAlchemy-compatible Postgres URI. Any standard `postgresql://` form works — DocsGPT normalizes it internally to the `psycopg` v3 dialect. | — |
| `AUTO_CREATE_DB` | On startup, connect to the server's `postgres` maintenance DB and issue `CREATE DATABASE` if the target is missing. Requires `CREATEDB` or superuser. No-op when the database already exists. Disable in production. | `true` |
| `AUTO_MIGRATE` | On startup, run `alembic upgrade head` against the target database. Idempotent and serialized across workers via `alembic_version`. Disable in production in favor of an explicit migration step. | `true` |

Example:

```env
POSTGRES_URI=postgresql://docsgpt:docsgpt@localhost:5432/docsgpt
# Append ?sslmode=require for managed providers that enforce SSL.
```

With the defaults, the app applies the schema automatically on first
boot. To run it explicitly instead (e.g., in CI/CD or a k8s `Job`):

```bash
python scripts/db/init_postgres.py
```

The default Docker Compose file bundles a `postgres` service, and the
app auto-bootstraps the database on boot, so containerized deployments
need no manual migration step. See
[PostgreSQL for User Data](/Deploying/Postgres-Migration#production-hardening)
for the recommended production flow (both flags `false`, migrations
gated by CI/CD).

<Callout type="info" emoji="ℹ️">
  `MONGO_URI` is **opt-in**. It is only consulted when you select the
  MongoDB Atlas vector-store backend (`VECTOR_STORE=mongodb`) or when
  running the one-shot `scripts/db/backfill.py` migration from a legacy
  Mongo-based install. Installing the optional Mongo client libraries
  requires `pip install 'pymongo>=4.6'`. See
  [PostgreSQL for User Data](/Deploying/Postgres-Migration) for the
  migration path.
</Callout>

## Retrieval & RAG Settings

These control how sources are retrieved and whether the advanced RAG features are available. See [Per-Source Configuration](/Sources/Per-source-configuration) and [GraphRAG](/Sources/GraphRAG) for details.

| Setting | Default | Description |
| --- | --- | --- |
| `RETRIEVERS_ENABLED` | `["classic", "default"]` | Allow-list of retrievers usable instance-wide. Valid keys: `classic`, `default`, `hybrid`, `graphrag`. A per-source `retriever` must be within this list. |
| `PER_SOURCE_RETRIEVAL_ENABLED` | `true` | Master switch for per-source retrieval config. When `false`, all sources fall back to the classic retriever regardless of their stored config. |
| `GRAPHRAG_ENABLED` | `false` | Enable [GraphRAG](/Sources/GraphRAG). Requires `VECTOR_STORE=pgvector`. |
| `GRAPHRAG_EXTRACTION_MODEL` | unset | Model used for ingest-time graph extraction. Unset reuses the instance default model. |
| `GRAPHRAG_MAX_CHUNKS_FOR_EXTRACTION` | `2000` | Hard cap on chunks extracted per source (cost control). |

## Embeddings Settings

See [Embeddings](/Models/embeddings) for full guidance.

| Setting | Default | Description |
| --- | --- | --- |
| `EMBEDDINGS_NAME` | `huggingface_sentence-transformers/all-mpnet-base-v2` | The embedding model. |
| `EMBEDDINGS_BASE_URL` | unset | Base URL of a remote OpenAI-compatible embeddings server. Setting it routes all embedding calls there. |
| `EMBEDDINGS_KEY` | unset | Optional bearer token for the remote embeddings server. |
| `EMBEDDINGS_MAX_INPUT_TOKENS` | unset | Truncate each remote embedding input to N tokens (guards servers that reject oversized inputs). |

## Tools Settings

| Setting | Default | Description |
| --- | --- | --- |
| `DEFAULT_CHAT_TOOLS` | `["memory", "read_webpage", "scheduler"]` | Tools enabled automatically in regular (agentless) chats. See [Tools Basics](/Tools/basics#default-chat-tools). |

## Admin & Access Settings

See [Access Control, Roles & Teams](/Deploying/Access-Control) for the full model.

| Setting | Default | Description |
| --- | --- | --- |
| `OIDC_ADMIN_GROUPS` | unset | Comma-separated IdP groups granted the global `admin` role (OIDC only). |
| `LOCAL_MODE_ADMIN` | `false` | Grants admin in no-auth mode (`AUTH_TYPE=None`) only. **Never enable on a networked deployment.** |

## LLM Provider Settings

| Setting | Default | Description |
| --- | --- | --- |
| `OPENAI_RESPONSES_STORE` | `false` | When `true`, allows OpenAI to persist [Responses API](/Models/cloud-providers#openai-responses-api-and-reasoning) state server-side. |

## Realtime Events Settings

The realtime notifications channel has its own settings — see [Realtime Events & Notifications](/Agents/notifications) (`ENABLE_SSE_PUSH`, `EVENTS_STREAM_MAXLEN`, `SSE_MAX_CONCURRENT_PER_USER`, and related).

## Exploring More Settings

These are just the basic settings to get you started. The `settings.py` file contains many more advanced options that you can explore to further customize DocsGPT, such as:

- Vector store configuration (`VECTOR_STORE`, Qdrant, Milvus, LanceDB settings) If you're looking for an easy way to set up a vector store with pgvector, try [Neon](https://get.neon.com/docsgpt).
- Retriever settings (`RETRIEVERS_ENABLED`)
- Cache settings (`CACHE_REDIS_URL`)
- And many more!

For a complete list of available settings and their descriptions, refer to the `settings.py` file in `application/core`. Remember to restart your Docker containers after making changes to your `.env` file or `settings.py` for the changes to take effect.