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 docsgpt/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: docsgpt/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: leave it unset and DocsGPT picks for you at first boot, recording the choice so it never changes underneath you: a fresh install is pinned to ibm-granite/granite-embedding-311m-multilingual-r2 (multilingual, 32k context, same 768 dimensions), and an install that already has sources is pinned to huggingface_sentence-transformers/all-mpnet-base-v2 so its index stays readable. Setting it here overrides that pin.
  • Other options: Any FastEmbed built-in model, or any Hugging Face repository shipping an ONNX export. See Embeddings.
  • Changing it on an existing index requires re-embedding — same-width models swap without any error and silently degrade retrieval. Run python -m docsgpt.scripts.reembed.

• 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=ibm-granite/granite-embedding-311m-multilingual-r2 # runs locally; see Models/embeddings for alternatives

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:

# /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 docsgpt/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 docsgpt/llm/providers/. See docsgpt/core/models/README.md for the full schema reference.

Docker

Mount the directory and set the env var:

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

Document Upload Limits

DocsGPT bounds public document and attachment uploads before storage or parsing. ZIP limits are cumulative across nested archives. Unsafe archive paths, duplicate file entries, encrypted members, symlinks, and other special files are rejected. Repeated directory records are ignored, and case-colliding names are disambiguated without overwriting either file. Nested archives expand into a directory named after the archive; files that merely end in .zip remain ordinary files.

These byte/count limits and the non-negative nesting depth can be overridden in .env. The request limit intentionally applies only to public upload routes; internal worker index transfers use their own trusted service boundary.

Document Parsing

Uploaded sources and chat attachments are converted to Markdown before chunking or prompting. See the Document Parsing and OCR guide for the engines and flows.

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.

Example: OpenAI Speech-to-Text

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

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.

Agent Image Settings

Agent avatars uploaded to DocsGPT must be valid PNG, JPEG, GIF, or WebP files. The decoded image and its file extension must agree; SVG and other formats are rejected. These limits apply before the image is written to local or S3 storage.

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.

How to Configure

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

# Shared signing key (required in production for every authentication mode)
JWT_SECRET_KEY=<long-random-value>

# No authentication (default)
AUTH_TYPE=None

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

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

# 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 signs authentication tokens where applicable and opaque agent-avatar capabilities in every authentication mode, including no-auth mode.
• Cloud and production deployments must set a strong JWT_SECRET_KEY, shared unchanged by every API and worker replica. Startup fails rather than creating replica-local keys when it is missing.
• Local development may omit it. DocsGPT atomically generates an owner-readable .jwt_secret_key in the project root and reuses it on later starts.

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:

    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.
  • 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.
• Keep the value stable. Rotating it invalidates active JWTs and previously generated agent-avatar URLs.

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.

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.

AWS S3

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:

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:

Example:

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

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 for the recommended production flow (both flags false, migrations gated by CI/CD).

Retrieval & RAG Settings

These control how sources are retrieved and whether the advanced RAG features are available. See Per-Source Configuration and GraphRAG for details.

Embeddings Settings

See Embeddings for full guidance.

Tools Settings

Admin & Access Settings

See Access Control, Roles & Teams for the full model.

LLM Provider Settings

Realtime Events Settings

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

Vector indexes on pgvector

DocsGPT does not create a vector index on the documents table, and for most deployments it should not have one. Exact search is correct and fast well past the size most corpora reach, and searches are filtered to a single source (WHERE source_id = ...) — a filter an approximate index applies only after picking its candidates.

That combination is what makes a badly-sized index dangerous rather than merely slow: the index picks candidates from the whole table, the source filter discards them, and the query returns too few rows or none at all, silently. The model then answers as if the source were empty.

If you have an existing documents_embedding_idx from an older version and your corpus is small (roughly under 50k vectors), drop it:

DROP INDEX IF EXISTS documents_embedding_idx;

DocsGPT still works with one in place — it raises ivfflat.probes to sqrt(lists) automatically and falls back to an exact search whenever an indexed search returns fewer rows than the source actually holds. You can pin probes explicitly with PGVECTOR_IVFFLAT_PROBES.

Only add an index once a corpus is genuinely large, size it to the data you actually have (IVFFlat’s lists guidance is roughly rows / 1000), and build it after the data is loaded — IVFFlat computes its cluster centroids at build time, so an index built on an empty table gets random centroids and never recovers.

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 .
• 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 docsgpt/core. Remember to restart your Docker containers after making changes to your .env file or settings.py for the changes to take effect.