Skip to main content
This page is for configuring your deployment.To find out more about configuring the Onyx app, checkout our Admin docs!

​
Configuring Onyx Deployments

Onyx offers a wide range of deployment-level configuration options. These are controlled via environment variables or through your deployment files.
If you don’t have a .env file:
cd onyx/deployment/docker_compose
cp env.prod.template .env

# If applicable
cp env.nginx.template .env.nginx
The template files have a subset of common environment variables provided for you. You can add more environment variables (listed below) to these .env files.Some configuration options must be set in your Docker Compose file.
The Docker Compose file you use to launch Onyx is the one you will need to modify. Likely either docker-compose.dev.yml or docker-compose.prod.yml.
Kubernetes deployments are configured using Helm charts. We have provided a values.yaml file where you can set all environment variables.
cd onyx/deployment/helm/charts/onyx
vim values.yaml
Add environment variables and secrets to the configMap and auth.secrets sections. A subset of common configuration options are provided for you. You can add more environment variables (listed below) to these sections.
Many configuration options are available in the Admin Panel! This page only covers deployment-level configuration.

​
Commonly Configured Options

​
Authentication

Basic Authentication

Set up email and password authentication.

Google OAuth

Authenticate with Google accounts.

OIDC

Single-sign on with OpenID Connect (OIDC)

SAML

Single-sign on with Security Assertion Markup Language (SAML)

​
Custom Domain

To host Onyx on a custom domain, set the WEB_DOMAIN environment variable and update your DNS records to point to your public Onyx deployment IP. For additional instructions, read the EC2 Deployment Guide!

​
SSL

If using Docker, the init-letsencrypt.sh script in onyx/deployment/docker_compose will automatically generate a Let’s Encrypt certificate and launch Onyx with SSL enabled. To enable the Web Search Tool, set the EXA_API_KEY environment variable.
Web Search in Onyx is continually developing and these instructions will be updated as we make improvements.

​
Logging

When self-hosting Onyx, you can configure the level of detail in the logs. This is helpful when troubleshooting issues. If using Docker, set LOG_LEVEL to debug in each container of your Docker Compose file. If using Kubernetes, set LOG_LEVEL to debug in your values.yaml file.

​
Observability

You can connect your observability tools to Onyx. We support the following providers: Braintrust (recommended) Braintrust is what we use internally for the cloud version of Onyx. Set the following environment variables: 
BRAINTRUST_PROJECT="Your project name"
BRAINTRUST_API_KEY="sk-..."
Langfuse 
LANGFUSE_SECRET_KEY="sk-..."
LANGFUSE_PUBLIC_KEY="pk-..."
LANGFUSE_BASE_URL="https://cloud.langfuse.com" # Or "https://us.cloud.langfuse.com"

​
Multilingual Configuration

Although Onyx assumes English by default, the system can be configured to support multiple languages in the Admin Panel and through environment variables.
  • Select a multi-lingual embedding model in the Search Settings of the Admin Panel
  • Set the following environment variables: 
MULTILINGUAL_QUERY_EXPANSION="English, French, YOUR_LANGUAGE_HERE"

LANGUAGE_HINT="IMPORTANT: ALWAYS RESPOND IN FRENCH! Even if the documents and the user query are in English, your response must be in French."
LANGUAGE_CHAT_NAMING_HINT="The name of the conversation must be in the same language as the user query."
Feel free to change the LANGUAGE_HINT and LANGUAGE_CHAT_NAMING_HINT prompts to your liking!

​
Onyx Environment Variables

This is not an exhaustive list of all Onyx environment variables.
SKIP_WARM_UP: Skip application warm-up process for hot-reloading the API server. Only set this for development purposes.WEB_DOMAIN: Set this if you are deploying Onyx on a custom domain.DISABLE_GENERATIVE_AI: Disable generative AI features.DISABLE_USER_KNOWLEDGE: Controls whether users can use the My Documents feature with assistants.ONYX_QUERY_HISTORY_TYPE: Controls query history reports (show user emails, anonymous, no queries)
AUTH_TYPE: Authentication type (disabled, basic, oauth, etc.)PASSWORD_MIN_LENGTH: For basic auth. The minimum password length requirementPASSWORD_MAX_LENGTH: For basic auth. The maximum password length requirementPASSWORD_REQUIRE_UPPERCASE: For basic auth. Require uppercase letters in passwordsPASSWORD_REQUIRE_LOWERCASE: For basic auth. Require lowercase letters in passwordsPASSWORD_REQUIRE_DIGIT: For basic auth. Require digits in passwordsPASSWORD_REQUIRE_SPECIAL_CHAR: For basic auth. Require special characters in passwordsENCRYPTION_KEY_SECRET: Enterprise Edition only. Key for encrypting connector credentials, API keys, etc.MASK_CREDENTIAL_PREFIX: Mask connector credentials in the admin UI. Turn off if admins should see the credentials in the admin panel.SESSION_EXPIRE_TIME_SECONDS: Session expiration time in seconds.AUTH_COOKIE_EXPIRE_TIME_SECONDS: JWT token validity duration in seconds.VALID_EMAIL_DOMAINS: Comma-separated list of allowed email domains.REQUIRE_EMAIL_VERIFICATION: Require email verification for registrationTRACK_EXTERNAL_IDP_EXPIRY: Honor the expires_at field returned by the external identity provider. Disabled be default because many auth providers have very short expiry times.
OAUTH_CLIENT_ID: For both Google OAuth and OIDC.OAUTH_CLIENT_SECRET: For both Google OAuth and OIDC.OPENID_CONFIG_URL: For OIDC.
Set the following for basic auth email verification and invites.
SMTP_SERVER: SMTP server hostnameSMTP_PORT: SMTP server portSMTP_USER: SMTP usernameSMTP_PASS: SMTP passwordEMAIL_FROM: From email addressSENDGRID_API_KEY: Alternative to SMTP for email delivery.ENABLE_EMAIL_INVITES: Enable email invitations
OAUTH_SLACK_CLIENT_ID: Slack OAuth client ID for Slack bot.OAUTH_SLACK_CLIENT_SECRET: Slack OAuth client secret for Slack bot.
POSTGRES_USER: PostgreSQL usernamePOSTGRES_PASSWORD: PostgreSQL passwordPOSTGRES_HOST: PostgreSQL hostPOSTGRES_PORT: PostgreSQL portPOSTGRES_DB: PostgreSQL database namePOSTGRES_API_SERVER_POOL_SIZE: API server connection pool sizePOSTGRES_API_SERVER_POOL_OVERFLOW: API server pool overflowPOSTGRES_API_SERVER_READ_ONLY_POOL_SIZE: Read-only pool sizePOSTGRES_API_SERVER_READ_ONLY_POOL_OVERFLOW: Read-only pool overflowPOSTGRES_USE_NULL_POOL: Use null connection poolPOSTGRES_POOL_PRE_PING: Enable connection pre-pingPOSTGRES_POOL_RECYCLE: Pool recycle timeout in secondsUSE_IAM_AUTH: Use IAM authentication for databaseDB_READONLY_USER: Read-only database userDB_READONLY_PASSWORD: Read-only database password
REDIS_SSL: Enable SSL for Redis connectionsREDIS_HOST: Redis hostREDIS_PORT: Redis portREDIS_PASSWORD: Redis passwordREDIS_REPLICA_HOST: Redis replica hostREDIS_DB_NUMBER: Redis database numberREDIS_DB_NUMBER_CELERY_RESULT_BACKEND: Celery result backend database numberREDIS_DB_NUMBER_CELERY: Celery broker database numberREDIS_HEALTH_CHECK_INTERVAL: Health check intervalREDIS_POOL_MAX_CONNECTIONS: Maximum pool connectionsREDIS_SSL_CERT_REQS: SSL certificate requirementsREDIS_SSL_CA_CERTS: SSL CA certificates
VESPA_HOST: Vespa hostVESPA_CONFIG_SERVER_HOST: Vespa config server hostVESPA_PORT: Vespa portVESPA_TENANT_PORT: Vespa tenant portNUM_RETRIES_ON_STARTUP: Startup connection attemptsVESPA_CLOUD_URL: Vespa Cloud URLVESPA_CLOUD_CERT_PATH: Vespa Cloud certificate pathVESPA_CLOUD_KEY_PATH: Vespa Cloud key pathMANAGED_VESPA: Use managed Vespa (Vespa Cloud)VESPA_REQUEST_TIMEOUT: Request timeout in secondsVESPA_LANGUAGE_OVERRIDE: Force Vespa language (en, de, etc.)
CELERY_RESULT_EXPIRES: Result expiration time in secondsCELERY_BROKER_POOL_LIMIT: Broker connection pool limitCELERY_WORKER_LIGHT_CONCURRENCY: Light worker concurrencyCELERY_WORKER_LIGHT_PREFETCH_MULTIPLIER: Light worker prefetch multiplierCELERY_WORKER_DOCPROCESSING_CONCURRENCY: Document processing worker concurrencyCELERY_WORKER_DOCFETCHING_CONCURRENCY: Document fetching worker concurrencyCELERY_WORKER_KG_PROCESSING_CONCURRENCY: Knowledge graph processing worker concurrency
These rate limits apply to auth endpoints
RATE_LIMIT_WINDOW_SECONDS: Rate limiting window in secondsRATE_LIMIT_MAX_REQUESTS: Maximum requests per windowREQUEST_TIMEOUT_SECONDS: Default request timeout
INDEX_BATCH_SIZE: Batch size during indexingDISABLE_INDEX_UPDATE_ON_SWAP: Disable primary index updates during embedding model swapsENABLE_MULTIPASS_INDEXING: Enable multipass indexing for better accuracyENABLE_CONTEXTUAL_RAG: Enable contextual retrievalSKIP_METADATA_IN_CHUNK: Skip metadata in chunksINDEXING_SIZE_WARNING_THRESHOLD: Size warning threshold in bytesINDEXING_EMBEDDING_MODEL_NUM_THREADS: Embedding model threadsCONTINUE_ON_CONNECTOR_FAILURE: Continue indexing on connector failuresMAX_DOCUMENT_CHARS: Maximum document charactersMAX_FILE_SIZE_BYTES: Maximum file size in bytesUSE_DOCUMENT_SUMMARY: Use document summary for contextual RAGUSE_CHUNK_SUMMARY: Use chunk summary for contextual RAG
Most of the settings below can be configured in the admin UI.
General Connector SettingsENABLED_CONNECTOR_TYPES: Comma-separated list of enabled connector typesLEAVE_CONNECTOR_ACTIVE_ON_INITIALIZATION_FAILURE: Keep connector active on init failureCURATORS_CANNOT_VIEW_OR_EDIT_NON_OWNED_ASSISTANTS: Restrict curator accessWeb ConnectorWEB_CONNECTOR_VALIDATE_URLS: Validate URLs in web connectorHTML_BASED_CONNECTOR_TRANSFORM_LINKS_STRATEGY: Link transformation strategyPARSE_WITH_TRAFILATURA: Use Trafilatura for HTML parsingConfluence ConnectorOAUTH_CONFLUENCE_CLOUD_CLIENT_ID: Confluence Cloud OAuth client IDOAUTH_CONFLUENCE_CLOUD_CLIENT_SECRET: Confluence Cloud OAuth client secretCONFLUENCE_CONNECTOR_LABELS_TO_SKIP: Labels to skip during indexingCONFLUENCE_CONNECTOR_ATTACHMENT_SIZE_THRESHOLD: Attachment size thresholdCONFLUENCE_CONNECTOR_ATTACHMENT_CHAR_COUNT_THRESHOLD: Attachment character thresholdCONFLUENCE_CONNECTOR_USER_PROFILES_OVERRIDE: User profiles override JSONCONFLUENCE_TIMEZONE_OFFSET: Timezone offset for CQL queriesGoogle Drive ConnectorOAUTH_GOOGLE_DRIVE_CLIENT_ID: Google Drive OAuth client IDOAUTH_GOOGLE_DRIVE_CLIENT_SECRET: Google Drive OAuth client secretMAX_DRIVE_WORKERS: Maximum Google Drive workersGOOGLE_DRIVE_CONNECTOR_SIZE_THRESHOLD: File size threshold for Google DriveSharePoint ConnectorSHAREPOINT_CONNECTOR_SIZE_THRESHOLD: File size threshold for SharePointJira ConnectorJIRA_CONNECTOR_LABELS_TO_SKIP: Labels to skip during indexingJIRA_CONNECTOR_MAX_TICKET_SIZE: Maximum ticket size in bytesGitHub ConnectorGITHUB_CONNECTOR_BASE_URL: GitHub base URL (for enterprise)GitLab ConnectorGITLAB_CONNECTOR_INCLUDE_CODE_FILES: Include code files in indexingGong ConnectorGONG_CONNECTOR_START_TIME: Start time for Gong connectorNotion ConnectorNOTION_CONNECTOR_DISABLE_RECURSIVE_PAGE_LOOKUP: Disable recursive page lookupZendesk ConnectorZENDESK_CONNECTOR_SKIP_ARTICLE_LABELS: Article labels to skipEgnyte IntegrationEGNYTE_CLIENT_ID: Egnyte OAuth client IDEGNYTE_CLIENT_SECRET: Egnyte OAuth client secretLinear IntegrationLINEAR_CLIENT_ID: Linear OAuth client IDLINEAR_CLIENT_SECRET: Linear OAuth client secret
ALLOW_SIMULTANEOUS_PRUNING: Allow simultaneous pruning operationsMAX_PRUNING_DOCUMENT_RETRIEVAL_PER_MINUTE: Maximum document retrieval rate during pruning
OKTA_PROFILE_TOOL_ENABLED: Enable Okta profile toolOKTA_API_TOKEN: Okta API token for SSWS auth
LOG_ONYX_MODEL_INTERACTIONS: Log Onyx model interactionsLOG_VESPA_TIMING_INFORMATION: Log Vespa query performanceLOG_ENDPOINT_LATENCY: Log endpoint latencyLOG_POSTGRES_LATENCY: Log PostgreSQL latencyLOG_POSTGRES_CONN_COUNTS: Log PostgreSQL connection counts
IMAGE_MODEL_NAME: Image model nameAZURE_IMAGE_API_VERSION: Azure OpenAI image API versionAZURE_IMAGE_API_KEY: Azure OpenAI key used for image generationAZURE_IMAGE_API_BASE: Azure OpenAI endpoint base URL for image generationAZURE_IMAGE_DEPLOYMENT_NAME: Azure OpenAI image deployment namespaceAZURE_DALLE_API_VERSION: Legacy alias for AZURE_IMAGE_API_VERSION (kept for backwards compatibility)AZURE_DALLE_API_KEY: Legacy alias for AZURE_IMAGE_API_KEY (kept for backwards compatibility)AZURE_DALLE_API_BASE: Legacy alias for AZURE_IMAGE_API_BASE (kept for backwards compatibility)AZURE_DALLE_DEPLOYMENT_NAME: Legacy alias for AZURE_IMAGE_DEPLOYMENT_NAME (kept for backwards compatibility)IMAGE_SUMMARIZATION_SYSTEM_PROMPT: System prompt for image summarizationIMAGE_SUMMARIZATION_USER_PROMPT: User prompt for image summarization
S3_FILE_STORE_BUCKET_NAME: S3 bucket name for file storageS3_FILE_STORE_PREFIX: S3 prefix for file storageS3_ENDPOINT_URL: S3 endpoint URL (for MinIO and other S3-compatible storage)S3_VERIFY_SSL: Verify SSL for S3 connectionsS3_AWS_ACCESS_KEY_ID: AWS access key ID for S3S3_AWS_SECRET_ACCESS_KEY: AWS secret access key for S3
DISABLE_TELEMETRY: Disable anonymous usage telemetryCUSTOM_ANSWER_VALIDITY_CONDITIONS: Custom answer validity conditions
API_PREFIX: Used to prepend a base path for all API routes. Set this to /api if you are running Onyx behind a reverse proxy that doesn’t support stripping the /api prefix from requests to the API server.API_KEY_HASH_ROUNDS: Hash rounds for API keysLLM_MODEL_UPDATE_API_URL: LLM model update API endpointLITELLM_CUSTOM_ERROR_MESSAGE_MAPPINGS: Custom error message mappings (JSON)GEN_AI_MODEL_FALLBACK_MAX_TOKENS: Maximum token limit for generative AI model fallback
Contact us to enable Enterprise Edition features!
DATA_PLANE_SECRET: Secret for secure control/data plane communicationEXPECTED_API_KEY: Additional security check for control plane APICONTROL_PLANE_API_BASE_URL: Control plane API base URL
DEV_MODE: Enable development modeINTEGRATION_TESTS_MODE: Enable integration tests modeMOCK_LLM_RESPONSE: Boolean to create mock LLM responses for testing
POD_NAME: Kubernetes pod namePOD_NAMESPACE: Kubernetes pod namespaceAWS_REGION_NAME: AWS region nameTARGET_AVAILABLE_TENANTS: Number of pre-provisioned tenants to maintainSYSTEM_RECURSION_LIMIT: System recursion limit

​
Enterprise Edition Environment Variables

Enterprise Edition adds additional environment variables to Onyx.
Setting this variable allows you to start your Onyx instance with pre-configured options that persist across restarts.ENV_SEED_CONFIGURATION accepts a JSON string with the following options:
  • llms: List of LLM configurations (name, provider, api_key, api_base, api_version, custom_config, default_model_name, fast_default_model_name)
  • admin_user_emails: List of email addresses for automatic admin role assignment
  • seeded_name: Pre-set name for your Onyx instance
  • seeded_logo_path: Path to your logo within the assets folder
This variable allows you to configure the number of rounds used in the SHA-256 Crypt hashing algorithm for API keys.
  • Default value: 535000
  • Allowed range: 1000 to 999999999
Increasing this value enhances security but may impact performance. The default value provides a good balance for most use cases.