Configuration

Ways to provide configuration

There are multiple ways to provide configuration to Erato.

All sources are configuration are merged together into one, so configuration can be specified via e.g. erato.toml, as well as via environment variables.

As of now, there is no specified precedence order when it comes to values provided for the same configuration key that are provided in different sources.

erato.toml files

The erato.toml file is the preferred way to provide configuration for Erato. The file must be placed in the current working directory of the Erato process.

In the Helm chart, a secret from where the erato.toml file should be mounted can be specified via backend.configFile.

*.auto.erato.toml files

In addition to the main erato.toml file, Erato will also auto-discover all files matching the pattern *.auto.erato.toml in the current working directory.

This is useful if you e.g. want to split out all the secret values (LLM API keys, Database credentials) into a different file that is not checked into source control.

Environment variables

Configuration can also be provided via environment variables.

Though it is not recommended, values for nested configuration can also be provided via environment variables. In that case, each nesting level is separated by double underscores (__). E.g. CHAT_PROVIDER__BASE_URL is equivalent to chat_provider.base_url.

Configuration reference

🚧Work in progress; Covers ~80% of available configuration options 🚧

frontend

frontend.theme

The name of the theme to use for the frontend.

When provided, the theme must be part of the frontend bundle (usually located in the public directory), and placed in the custom-theme directory, under the name provided here. E.g. if frontend.theme is set to my-theme, the theme must be placed in public/custom-theme/my-theme.

See Theming for more information about themes and theme directory structure.

If not provided, the default bundled theme will be used.

Default value: None

Type: string | None

Example

[frontend]
theme = "my-theme"

frontend.disable_upload

Whether to disable file upload functionality in the UI. This is useful for embedded scenarios where file uploads should not be available.

Default value: false

Type: boolean

Example

[frontend]
disable_upload = true

frontend.disable_chat_input_autofocus

Whether to disable automatic focusing of the chat input field. This prevents unwanted scrolling behavior when navigating to pages with embedded chat widgets.

When enabled, the chat input field will not automatically receive focus on page load/navigation.

Default value: false

Type: boolean

Example

[frontend]
disable_chat_input_autofocus = true

frontend.disable_logout

Whether to hide logout functionality from the UI. This is useful for embedded scenarios where logout should be handled by the parent application.

When enabled, the logout button/option will be hidden from the user interface.

Default value: false

Type: boolean

Example

[frontend]
disable_logout = true

frontend.additional_environment

Additional values to inject into the frontend environment as global variables. These will be made available to the frontend Javascript, and added to the window object.

This is a dictionary where each value can be a string or a map (string key, string value).

This may be useful if you are using a forked version of the frontend, which you need to pass some configuration to.

Default value: None

Type: object<string, any>

Example

[frontend]
additional_environment = { "FOO": "bar" }

This will be inejcted into the frontend as:

window.FOO = "bar";

chat_provider (deprecated)

⚠️ Deprecated: Please use chat_providers instead for multiple provider support and better flexibility.

Configuration for a single chat provider (LLM) that Erato will use for generating responses. This is maintained for backward compatibility but will be automatically migrated to the new chat_providers format.

chat_provider.provider_kind

The type of chat provider to use.

Type: string

Supported values: "openai", "azure_openai"

Example: "openai"

chat_provider.model_name

The name of the model to use with the chat provider.

Type: string

Example: "gpt-4o"

chat_provider.model_display_name

The display name for the model shown to users. If not provided, falls back to model_name.

Type: string | None

Example: "GPT-4 Omni (Production)"

chat_provider.base_url

The base URL for the chat provider API. If not provided, will use the default for the provider.

Type: string | None

Example: "https://api.openai.com/v1/", "http://localhost:11434/v1/"

chat_provider.api_key

The API key for the chat provider.

Type: string | None

Example: "sk-..."

chat_provider.system_prompt

A static system prompt to use with the chat provider. This sets the behavior and personality of the AI assistant.

Type: string | None

Note: This option is mutually exclusive with system_prompt_langfuse.

Example:

[chat_provider]
provider_kind = "openai"
model_name = "gpt-4"
system_prompt = "You are a helpful assistant that provides concise and accurate answers."

chat_provider.system_prompt_langfuse

Configuration for using a system prompt from Langfuse prompt management instead of a static prompt.

Type: object | None

Note: This option is mutually exclusive with system_prompt. Requires the Langfuse integration to be enabled.

Properties:

• prompt_name (string): The name of the prompt in Langfuse to use

Example:

[chat_provider]
provider_kind = "openai"
model_name = "gpt-4"
system_prompt_langfuse = { prompt_name = "assistant-prompt-v1" }
 
[integrations.langfuse]
enabled = true
base_url = "https://cloud.langfuse.com"
public_key = "pk-lf-..."
secret_key = "sk-lf-..."

chat_providers

Configuration for multiple chat providers with priority ordering. This is the recommended way to configure chat providers as it supports multiple providers, fallback mechanisms, and better flexibility.

chat_providers.priority_order

An ordered list of provider IDs that defines the priority for provider selection. The first provider in the list has the highest priority.

Type: array of strings

Required: Yes

Example: ["primary", "backup", "local"]

chat_providers.providers

A map of provider configurations, where each key is a unique provider ID and the value is a provider configuration object.

Type: object

Required: Yes

Example:

[chat_providers]
priority_order = ["primary", "backup"]
 
[chat_providers.providers.primary]
provider_kind = "openai"
model_name = "gpt-4"
model_display_name = "GPT-4 (Primary)"
api_key = "sk-primary-key"
 
[chat_providers.providers.primary.model_capabilities]
context_size_tokens = 8192
supports_image_understanding = false
cost_input_tokens_per_1m = 30.0
cost_output_tokens_per_1m = 60.0
 
[chat_providers.providers.backup]
provider_kind = "openai"
model_name = "gpt-3.5-turbo"
model_display_name = "GPT-3.5 Turbo (Backup)"
api_key = "sk-backup-key"
base_url = "https://api.backup-provider.com/v1/"
 
[chat_providers.providers.backup.model_capabilities]
context_size_tokens = 16385
supports_image_understanding = false
cost_input_tokens_per_1m = 1.0
cost_output_tokens_per_1m = 2.0

Provider Configuration Fields

Each provider in chat_providers.providers supports the following fields:

• provider_kind - The type of chat provider ("openai", "azure_openai", "ollama")
• model_name - The model identifier for the provider
• model_display_name - Optional display name for the model (falls back to model_name)
• api_key - Optional API key for authentication
• base_url - Optional custom base URL for the provider API
• system_prompt - Optional static system prompt
• system_prompt_langfuse - Optional Langfuse prompt configuration (mutually exclusive with system_prompt)
• additional_request_parameters - Optional array of additional request parameters
• additional_request_headers - Optional array of additional request headers
• model_capabilities - Optional configuration for model capabilities and limitations

model_capabilities

The model_capabilities field allows you to configure the capabilities and limitations of each chat provider’s model. This information is used for token usage estimation, cost calculation, and determining which features are available.

Type: object | None

Example:

[chat_providers.providers.main.model_capabilities]
context_size_tokens = 128000
supports_image_understanding = true
supports_reasoning = false
supports_verbosity = false
cost_input_tokens_per_1m = 5.0
cost_output_tokens_per_1m = 15.0

Fields:

• context_size_tokens (default: 1000000) - Maximum number of tokens that may be provided to the model including input messages, system prompt, and files
• supports_image_understanding (default: false) - Whether the model supports being provided with images for understanding
• supports_reasoning (default: false) - Whether the model supports reasoning mode (e.g., OpenAI o1 family)
• supports_verbosity (default: false) - Whether the model supports providing a verbosity parameter (for future support of advanced models)
• cost_input_tokens_per_1m (default: 0.0) - Price per 1 million input tokens (unit-less, for cost estimation)
• cost_output_tokens_per_1m (default: 0.0) - Price per 1 million output tokens (unit-less, for cost estimation)

If not explicitly configured, all capabilities default to conservative values (large context window, no special features, no cost tracking).

chat_providers.summary

Configuration for chat summary generation. This allows you to specify which provider and settings to use when generating chat summaries.

Type: object | None

Example:

[chat_providers.summary]
summary_chat_provider_id = "summarizer"
max_tokens = 150

chat_providers.summary.summary_chat_provider_id

The ID of the chat provider to use specifically for generating chat summaries. This provider must exist in the chat_providers.providers map.

If not specified, Erato will use the highest priority provider from priority_order for summary generation.

Type: string | None

Default value: None (uses highest priority provider)

Example: "summarizer"

chat_providers.summary.max_tokens

The maximum number of output tokens to allow when generating chat summaries. This helps control the length and cost of summary generation.

Type: number | None

Default value: 300

Example: 150

Complete Example:

[chat_providers]
priority_order = ["main"]
 
[chat_providers.summary]
summary_chat_provider_id = "summarizer"
max_tokens = 150
 
[chat_providers.providers.main]
provider_kind = "openai"
model_name = "gpt-4"
api_key = "sk-main-key"
 
[chat_providers.providers.summarizer]
provider_kind = "openai"
model_name = "gpt-4o-mini"
model_display_name = "GPT-4o Mini (Summarizer)"
api_key = "sk-summarizer-key"

In this example:

• Regular chat interactions use the “main” provider (GPT-4)
• Chat summaries are generated using the “summarizer” provider (GPT-4o Mini)
• Summary generation is limited to 150 output tokens
• This allows using a faster, cheaper model for summaries while keeping a more powerful model for main interactions

Migration from chat_provider

If you’re using the old chat_provider configuration, it will be automatically migrated to the new format:

• The old provider will be given the ID "default"
• The priority order will be set to ["default"]
• A deprecation warning will be logged

Before (deprecated):

[chat_provider]
provider_kind = "openai"
model_name = "gpt-4"
api_key = "sk-key"

After (recommended):

[chat_providers]
priority_order = ["main"]
 
[chat_providers.providers.main]
provider_kind = "openai"
model_name = "gpt-4"
api_key = "sk-key"

file_storage_providers

Configuration for file storage providers that handle uploaded files and documents in Erato. You can configure multiple storage providers with different backends (S3-compatible or Azure Blob Storage) and designate one as the default.

Type: object<string, FileStorageProviderConfig>

Required: At least one file storage provider must be configured.

Example:

[file_storage_providers.primary]
provider_kind = "s3"
display_name = "Primary Storage"
max_upload_size_kb = 102400  # 100 MB
config = { bucket = "erato-files", region = "us-east-1", access_key_id = "AKIAIOSFODNN7EXAMPLE", secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" }
 
# Set which provider to use as default
default_file_storage_provider = "primary"

file_storage_providers.<provider_id>.provider_kind

The type of file storage backend to use.

Type: string

Required: Yes

Supported values:

• "s3" - Amazon S3 or services that expose an S3-compatible API (e.g., MinIO, DigitalOcean Spaces, Cloudflare R2)
• "azblob" - Azure Blob Storage

Example: "s3" or "azblob"

file_storage_providers.<provider_id>.display_name

A human-readable name to display in the UI for this storage provider.

Type: string | None

Default: Falls back to the provider ID if not specified

Example: "Primary Storage" or "Azure Backup Storage"

file_storage_providers.<provider_id>.max_upload_size_kb

The maximum file size that may be uploaded in kilobytes. This limit is enforced by the backend.

Type: number | None

Default: No limit (system default applies)

Example: 102400 (100 MB), 10240 (10 MB)

file_storage_providers.<provider_id>.config

Provider-specific configuration object. The available fields depend on the provider_kind.

Type: object

Required: Yes

S3 Provider Configuration

When provider_kind = "s3", the following configuration fields are available:

bucket (required)

The name of the S3 bucket to store files in.

Type: string

Example: "erato-files", "my-company-documents"

endpoint (optional)

The S3-compatible endpoint URL. Use this when connecting to S3-compatible services other than AWS S3 (e.g., MinIO, DigitalOcean Spaces).

If not specified, defaults to AWS S3.

Type: string | None

Example: "https://nyc3.digitaloceanspaces.com", "http://localhost:9000"

region (optional)

The AWS region where the bucket is located.

Type: string | None

Example: "us-east-1", "eu-central-1"

root (optional)

A prefix path within the bucket where files should be stored. Useful for organizing files or sharing buckets across multiple applications.

Type: string | None

Example: "erato-uploads/", "production/files/"

access_key_id (optional)

The AWS access key ID for authentication. If not provided, the SDK will attempt to use environment variables or instance credentials.

Type: string | None

Example: "AKIAIOSFODNN7EXAMPLE"

secret_access_key (optional)

The AWS secret access key for authentication. If not provided, the SDK will attempt to use environment variables or instance credentials.

Type: string | None

Example: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Complete S3 Example:

[file_storage_providers.s3_primary]
provider_kind = "s3"
display_name = "AWS S3 Primary"
max_upload_size_kb = 204800  # 200 MB
config = { bucket = "erato-production-files", region = "us-west-2", root = "uploads/", access_key_id = "AKIAIOSFODNN7EXAMPLE", secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" }
 
default_file_storage_provider = "s3_primary"

MinIO Example:

[file_storage_providers.minio]
provider_kind = "s3"
display_name = "MinIO Local Storage"
max_upload_size_kb = 102400  # 100 MB
config = { bucket = "erato-storage", endpoint = "http://localhost:9000", access_key_id = "minioadmin", secret_access_key = "minioadmin" }
 
default_file_storage_provider = "minio"

Azure Blob Storage Configuration

When provider_kind = "azblob", the following configuration fields are available:

container (required)

The name of the Azure Blob Storage container to store files in.

Type: string

Example: "erato-files", "documents"

endpoint (required)

The Azure Blob Storage endpoint URL for your storage account.

Type: string

Example: "https://mystorageaccount.blob.core.windows.net"

root (optional)

A prefix path within the container where files should be stored. Useful for organizing files or sharing containers across multiple applications.

Type: string | None

Example: "erato-uploads/", "production/files/"

account_name (optional)

The Azure storage account name for authentication. If not provided, the SDK will attempt to use environment variables or managed identity.

Type: string | None

Example: "mystorageaccount"

account_key (optional)

The Azure storage account key for authentication. If not provided, the SDK will attempt to use environment variables or managed identity.

Type: string | None

Example: "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw=="

Complete Azure Blob Storage Example:

[file_storage_providers.azure]
provider_kind = "azblob"
display_name = "Azure Blob Storage"
max_upload_size_kb = 153600  # 150 MB
config = { endpoint = "https://mycompany.blob.core.windows.net", container = "erato-files", root = "uploads/", account_name = "mycompany", account_key = "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==" }
 
default_file_storage_provider = "azure"

Azurite (Azure Blob Storage Emulator) Example:

[file_storage_providers.azurite]
provider_kind = "azblob"
display_name = "Azurite Local Storage"
max_upload_size_kb = 102400  # 100 MB
config = { endpoint = "http://127.0.0.1:10000/devstoreaccount1", container = "erato-storage", account_name = "devstoreaccount1", account_key = "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==" }
 
default_file_storage_provider = "azurite"

default_file_storage_provider

Specifies which file storage provider to use as the default for new file uploads. This must match one of the keys in the file_storage_providers map.

When multiple file storage providers are configured, this setting is required and determines where new files will be written. All configured providers remain available for reading existing files, which is useful for migration scenarios.

Type: string | None

Required when: Multiple file storage providers are configured

Example: "primary", "s3_main", "azure"

Note: This is a top-level configuration key, not nested under file_storage_providers.

Configuration Example:

# Define multiple providers
[file_storage_providers.primary]
provider_kind = "s3"
display_name = "Primary Storage"
max_upload_size_kb = 102400
config = { bucket = "erato-files", region = "us-east-1" }
 
[file_storage_providers.backup]
provider_kind = "azblob"
display_name = "Backup Storage"
max_upload_size_kb = 102400
config = { endpoint = "https://backup.blob.core.windows.net", container = "erato-backup" }
 
# Specify which one is default (top-level key)
default_file_storage_provider = "primary"

In this example:

• New files will be uploaded to the “primary” S3 provider
• Existing files can still be read from both “primary” and “backup” providers
• This allows migrating from one storage provider to another without data loss

Multiple Providers Example

You can configure multiple file storage providers. This is currently mainly useful for migration scenarios, where new file uploads should be read + written from a new file storage provider, but past uploaded files should still be available to be read from an older file storage provider.

# Primary S3 storage
[file_storage_providers.s3_primary]
provider_kind = "s3"
display_name = "S3 Primary (US)"
max_upload_size_kb = 204800  # 200 MB
config = { bucket = "erato-us-files", region = "us-east-1", access_key_id = "AKIAIOSFODNN7EXAMPLE", secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" }
 
# Backup Azure storage
[file_storage_providers.azure_backup]
provider_kind = "azblob"
display_name = "Azure Backup (EU)"
max_upload_size_kb = 204800  # 200 MB
config = { endpoint = "https://eratoeu.blob.core.windows.net", container = "erato-eu-files", account_name = "eratoeu", account_key = "..." }
 
# Set default provider
default_file_storage_provider = "s3_primary"

model_permissions

Configuration for controlling user access to chat providers based on user attributes like group membership. This allows you to implement fine-grained access control, such as restricting premium models to certain user groups or providing different models to different teams.

Type: object | None

Default behavior: If no model permissions are configured, all users have access to all configured chat providers.

model_permissions.rules

A map of permission rules, where each key is a unique rule name and the value is a rule configuration object. Rules are evaluated independently, and if any rule grants access to a chat provider, the user is allowed to use it.

Type: object<string, ModelPermissionRule>

Example:

[model_permissions.rules.basic_access]
rule_type = "allow-all"
chat_provider_ids = ["gpt-4o-mini"]
 
[model_permissions.rules.premium_access]
rule_type = "allow-for-group-members"
chat_provider_ids = ["gpt-4", "claude-3-opus"]
groups = ["premium-users", "administrators"]
 
[model_permissions.rules.admin_only]
rule_type = "allow-for-group-members"
chat_provider_ids = ["gpt-4-turbo", "experimental-model"]
groups = ["administrators"]

Rule Types

There are two types of permission rules:

allow-all

Grants access to specified chat providers for all users, regardless of their group membership.

Fields:

• rule_type - Must be "allow-all"
• chat_provider_ids - Array of chat provider IDs that this rule grants access to

Example:

[model_permissions.rules.public_models]
rule_type = "allow-all"
chat_provider_ids = ["gpt-4o-mini", "claude-3-haiku"]

allow-for-group-members

Grants access to specified chat providers only for users who belong to at least one of the specified groups. User groups are derived from the groups claim in the user’s ID token (see SSO/OIDC configuration).

Fields:

• rule_type - Must be "allow-for-group-members"
• chat_provider_ids - Array of chat provider IDs that this rule grants access to
• groups - Array of group names/identifiers that are allowed access

Example:

[model_permissions.rules.premium_models]
rule_type = "allow-for-group-members"
chat_provider_ids = ["gpt-4", "claude-3-opus"]
groups = ["premium-subscribers", "enterprise-users"]

How Permission Evaluation Works

1. No rules configured: All users have access to all chat providers
2. Rules configured: For each chat provider, check if any rule grants access:
   • allow-all rules always grant access
   • allow-for-group-members rules grant access only if the user belongs to at least one specified group
3. Access granted: If any rule grants access to a chat provider, the user can use it
4. Access denied: If no rules grant access to a chat provider, it’s hidden from the user

Complete Example

# Chat provider configuration
[chat_providers]
priority_order = ["basic", "premium", "experimental"]
 
[chat_providers.providers.basic]
provider_kind = "openai"
model_name = "gpt-4o-mini"
model_display_name = "GPT-4o Mini (Basic)"
api_key = "sk-basic-key"
 
[chat_providers.providers.premium]
provider_kind = "openai"
model_name = "gpt-4"
model_display_name = "GPT-4 (Premium)"
api_key = "sk-premium-key"
 
[chat_providers.providers.experimental]
provider_kind = "openai"
model_name = "gpt-4-turbo"
model_display_name = "GPT-4 Turbo (Experimental)"
api_key = "sk-experimental-key"
 
# Model permissions configuration
[model_permissions.rules.basic_access]
rule_type = "allow-all"
chat_provider_ids = ["basic"]
 
[model_permissions.rules.premium_access]
rule_type = "allow-for-group-members"
chat_provider_ids = ["premium"]
groups = ["premium-users", "enterprise"]
 
[model_permissions.rules.experimental_access]
rule_type = "allow-for-group-members"
chat_provider_ids = ["experimental"]
groups = ["beta-testers", "administrators"]

In this example:

• All users can access the “basic” model (GPT-4o Mini)
• Premium users and enterprise users can access both “basic” and “premium” models
• Beta testers and administrators can access “basic”, “premium” (if they’re also in premium groups), and “experimental” models
• Regular users (not in any special groups) can only access the “basic” model

Integration with SSO/OIDC

Model permissions rely on group information from the user’s ID token. The groups claim in the JWT token is parsed and used for permission evaluation. See the SSO/OIDC documentation for information on how to configure your identity provider to include group information in ID tokens.

Common group claim formats:

• Array of strings: ["group1", "group2", "group3"]
• Single string: "group1" (automatically converted to array)

If no groups claim is present in the ID token, the user is treated as having no group memberships, and only allow-all rules will grant them access.

integrations

Configuration for external service integrations.

integrations.langfuse

Configuration for the Langfuse observability and prompt management integration.

integrations.langfuse.enabled

Whether the Langfuse integration is enabled.

Default value: false

Type: boolean

integrations.langfuse.base_url

The base URL for your Langfuse instance. Use https://cloud.langfuse.com for Langfuse Cloud or your self-hosted URL.

Required when enabled: Yes

Type: string

Example: "https://cloud.langfuse.com" or "https://langfuse.yourcompany.com"

integrations.langfuse.public_key

Your Langfuse project’s public key. You can find this in your Langfuse project settings.

Required when enabled: Yes

Type: string

Example: "pk-lf-1234567890abcdef"

integrations.langfuse.secret_key

Your Langfuse project’s secret key. You can find this in your Langfuse project settings.

Required when enabled: Yes

Type: string

Example: "sk-lf-abcdef1234567890"

integrations.langfuse.tracing_enabled

Whether to enable detailed tracing of LLM interactions. When enabled, all chat completions will be logged to Langfuse.

Default value: false

Type: boolean

See the Langfuse Integration documentation for detailed usage instructions and feature descriptions.

integrations.sentry

Configuration for the Sentry error reporting and performance monitoring integration.

integrations.sentry.sentry_dsn

The Sentry DSN (Data Source Name) for your Sentry project. This enables error reporting and performance monitoring.

Default value: None

Type: string | None

Example:

[integrations.sentry]
sentry_dsn = "https://public@sentry.example.com/1"

See the Sentry Integration documentation for detailed setup instructions.

mcp_servers

Configuration for Model Context Protocol (MCP) servers that extend Erato’s capabilities through custom tools and integrations.

Type: object<string, McpServerConfig>

Example:

[mcp_servers.file_provider]
transport_type = "sse"
url = "http://127.0.0.1:63490/sse"
 
[mcp_servers.filesystem]
transport_type = "sse"
url = "https://my-mcp-server.example.com/sse"
http_headers = { "Authorization" = "Bearer token123", "X-API-Key" = "key456" }

mcp_servers.<server_id>.transport_type

The type of transport protocol used to communicate with the MCP server.

Type: string

Supported values:

• "sse" (Server-Sent Events)
• "streamable_http" (Streamable HTTP)

Example: "sse" or "streamable_http"

mcp_servers.<server_id>.url

The URL endpoint for the MCP server.

• For transport_type = "sse", this conventionally ends with /sse
• For transport_type = "streamable_http", this should be the base HTTP endpoint

Type: string

Example: "http://127.0.0.1:63490/sse", "https://my-mcp-server.example.com/sse", "https://api.example.com/mcp"

mcp_servers.<server_id>.http_headers

Optional static HTTP headers to include with every request to the MCP server. This is useful for authentication or API keys.

Type: object<string, string> | None

Example:

[mcp_servers.authenticated_server]
transport_type = "sse"
url = "https://secure-mcp-server.example.com/sse"
http_headers = { "Authorization" = "Bearer your-token", "X-API-Key" = "your-api-key" }

See the MCP Servers documentation for more information about Model Context Protocol integration.

budget

Configuration for budget tracking and display functionality. This feature allows you to track and display per-user spending based on token usage and model pricing.

Type: object

Default behavior: Budget tracking is disabled by default.

Example:

[budget]
enabled = true
max_budget = 100.0
budget_currency = "USD"
warn_threshold = 0.8
budget_period_days = 30

budget.enabled

Whether budget tracking and display is enabled. When disabled, no budget information will be calculated or displayed to users.

Type: boolean

Default value: false

Example: true

budget.max_budget

The maximum budget amount per budget period (unit-less). This value is used for calculating budget usage percentages and determining when warning thresholds are exceeded.

The budget amount is treated as unit-less for flexibility - the actual monetary value depends on your model pricing configuration and the configured display currency.

Type: number | None

Required when: budget.enabled = true

Example: 100.0

budget.budget_currency

The currency to use for display purposes in the frontend. This is purely cosmetic and doesn’t affect calculations - all budget amounts and costs are treated as unit-less values.

Type: string

Supported values: "USD", "EUR"

Default value: "USD"

Example: "EUR"

budget.warn_threshold

The threshold (between 0.0 and 1.0) at which to warn users about budget usage. When a user’s spending exceeds this percentage of their budget limit, they will receive warnings in the UI.

For example, a value of 0.7 means users will be warned when they’ve used 70% of their budget.

Type: number

Default value: 0.7

Valid range: 0.0 to 1.0

Example: 0.8

budget.budget_period_days

Number of days that counts as one budget period. Budget usage is calculated and reset based on this period length.

Type: number

Default value: 30

Example: 7 (for weekly budgets), 30 (for monthly budgets)

Complete Budget Configuration Example

[budget]
enabled = true
max_budget = 50.0
budget_currency = "EUR"
warn_threshold = 0.75
budget_period_days = 7
 
# You also need to configure model pricing for accurate cost calculations
[chat_providers]
priority_order = ["main"]
 
[chat_providers.providers.main]
provider_kind = "openai"
model_name = "gpt-4o"
api_key = "sk-your-key"
 
[chat_providers.providers.main.model_capabilities]
cost_input_tokens_per_1m = 5.0
cost_output_tokens_per_1m = 15.0

Note: Budget tracking requires that you configure accurate pricing information in your chat provider’s model_capabilities section. The budget calculations are based on actual token usage multiplied by the configured token prices.