Skip to main content

CodeMie API Configuration Reference

This document provides a comprehensive reference for all configuration parameters available in the CodeMie API.

These parameters control application behavior, AI provider integrations, tools configuration, storage, security, and more. Configure them through environment variables or .env files.

Core Application Settings​

These settings control fundamental application behavior, deployment environment, and runtime characteristics.

Application Metadata​

ParameterTypeDefaultDescription
APP_VERSIONstring"0.16.0"Application version displayed in UI and logs for tracking deployments
ENVstring"local"Deployment environment identifier affecting logging format and feature flags
MODELS_ENVstring"dial"LLM configuration profile to load (points to llm-{value}-config.yaml)
LOG_LEVELstring"INFO"Minimum log severity to output; use DEBUG for troubleshooting, INFO for production
TIMEZONEstring"UTC"System timezone for timestamp normalization across distributed components
API_ROOT_PATHstring""URL prefix for API endpoints when behind reverse proxy (e.g., /api/v1)
WORKERSinteger1Uvicorn worker processes; increase for production to handle concurrent requests
HTTPS_VERIFY_SSLbooleantrueVerify SSL certificates for outbound HTTP requests; disable only in controlled development environments with self-signed certificates

Callback Configuration​

ParameterTypeDefaultDescription
CALLBACK_API_BASE_URLstring"http://host.docker.internal:8080"Base URL for asynchronous webhook callbacks from external services

Mermaid Diagram Rendering​

Converts Mermaid diagram syntax to images for documentation and visualizations.

ParameterTypeDefaultDescription
MERMAID_SERVER_URLstring"http://localhost:8082"Local Mermaid rendering service URL for diagram generation
MERMAID_SERVER_TIMEOUTinteger50Max seconds to wait for diagram rendering before timeout
MERMAID_USE_MERMAID_INCbooleanfalseUse public Mermaid Inc. service (requires outbound internet connection) or locally installed server

Agent-to-Agent (A2A) Communication​

Enable CodeMie agents to communicate with external AI agents and services.

ParameterTypeDefaultDescription
A2A_AGENT_CARD_FETCH_TIMEOUTfloat30.0Max seconds to fetch agent capability cards for discovery
A2A_AGENT_REQUEST_TIMEOUTfloat30.0Max seconds to wait for responses from external agents
A2A_PROVIDER_ORGANIZATIONstring""Organization identifier sent to external A2A providers for routing and auth context
A2A_PROVIDER_URLstring""Base URL of the external A2A provider endpoint

Datasource Indexing Concurrency​

Limit simultaneous datasource indexing operations to prevent overloading backend resources.

ParameterTypeDefaultDescription
DATASOURCE_CONCURRENCY_LIMIT_ENABLEDbooleanfalseEnable concurrency limiting for datasource indexing operations
MAX_CONCURRENT_DATASOURCE_INDEXINGinteger5Max number of datasource indexing jobs that can run simultaneously
DATASOURCE_QUEUE_TIMEOUTinteger3600Max seconds an indexing job can wait in the queue before timing out; 0 disables the timeout

Stale Indexing Watchdog​

ParameterTypeDefaultDescription
STALE_INDEXING_WATCHDOG_ENABLEDbooleanfalseEnable background watchdog that detects and resets datasource indexing jobs stuck in-progress

Platform & Marketplace​

Configure marketplace integration for sharing and discovering assistants.

ParameterTypeDefaultDescription
PLATFORM_MARKETPLACE_DATASOURCE_NAMEstring"marketplace_assistants"Datasource name for marketplace assistant catalog
PLATFORM_DATASOURCES_SYNC_ENABLEDbooleanfalseAutomatically sync platform datasources on startup

State Management & Import/Export​

Configure data migration, backup, and state import/export capabilities.

ParameterTypeDefaultDescription
STATE_IMPORT_DIRstring"./state_import"Directory containing state files for bulk import
STATE_IMPORT_ENABLEDbooleanfalseEnable state import on startup (for migrations)
CODEMIE_EXPORT_ROOTstring"/app"Root path for exported data and backups
THREAD_POOL_MAX_WORKERSinteger20Worker threads for parallel background tasks
ASSISTANT_THREAD_POOL_MAX_WORKERSinteger60Dedicated thread pool size for assistant request processing

Feature Flags & Experimental Features​

Enable or disable experimental features and beta functionality.

ParameterTypeDefaultDescription
AMNA_AIRN_PRECREATE_WORKFLOWSbooleanfalsePre-create AMNA-AIRN workflows on deployment (beta feature)
LLM_REQUEST_ADD_MARKDOWN_PROMPTbooleantrueAdd markdown formatting hint to improve LLM output structure
MARKETPLACE_LLM_VALIDATION_ON_PUBLISH_ENABLEDbooleantrueRun LLM-based quality validation when publishing an assistant to the marketplace; disable to skip validation and allow any assistant to be published without review
HIDE_AGENT_STREAMING_EXCEPTIONSbooleanfalseSuppress agent exceptions from being surfaced in the UI response stream; useful to hide internal errors from end-users in production

Support & Help​

ParameterTypeDefaultDescription
CODEMIE_SUPPORTstring"https://epa.ms/codemie-support"URL for user support and documentation portal

Configuration File Paths​

These parameters define paths to configuration files and directories. Typically auto-detected and rarely need manual configuration.

ParameterTypeDefaultDescription
PROJECT_ROOTPathAuto-detectedProject root directory (auto-detected from installation)
LLM_TEMPLATES_ROOTPathconfig/llmsDirectory containing LLM model configuration YAML files
DATASOURCES_CONFIG_DIRPathconfig/datasourcesDatasource connector definitions and schemas
ASSISTANT_TEMPLATES_DIRPathconfig/templates/assistantPre-built assistant templates for quick setup
WORKFLOW_TEMPLATES_DIRPathconfig/templates/workflowWorkflow templates for common automation patterns
SKILL_TEMPLATES_DIRPathconfig/templates/skillDirectory scanned at startup to discover and upsert built-in skill templates into the database
CUSTOMER_CONFIG_DIRPathconfig/customerCustomer-specific customizations and branding
ASSISTANT_CATEGORIES_CONFIG_DIRPathconfig/categoriesAssistant categorization and organization
AUTHORIZED_APPS_CONFIG_DIRPathconfig/authorized_applicationsExternal application access control definitions
INDEX_DUMPS_DIRPathconfig/index-dumpsPre-built index snapshots for faster deployment
ALEMBIC_MIGRATIONS_DIRPathexternal/alembicDatabase schema migration scripts
ALEMBIC_INI_PATHPathexternal/alembic/alembic.iniAlembic database migration configuration

AI Providers Configuration​

Configure connections to AI model providers. At least one provider must be configured for CodeMie to function.

OpenAI / Azure OpenAI​

For LLMs and embedding models via Azure OpenAI Service.

ParameterTypeDefaultDescription
OPENAI_API_TYPEstring"azure"Provider type: azure for Azure OpenAI, openai for direct OpenAI API
OPENAI_API_VERSIONstring"2025-04-01-preview"Azure OpenAI API version; update to access new features or model capabilities
AZURE_OPENAI_API_KEYstring""Authentication key from Azure OpenAI resource (required for Azure deployments)
AZURE_OPENAI_URLstring""Azure OpenAI endpoint URL from resource overview page
AZURE_OPENAI_MAX_RETRIESinteger5Retry attempts for failed requests due to rate limits or transient errors

Anthropic (Claude)​

For Claude (Sonnet and Haiku models) via Anthropic's native API.

ParameterTypeDefaultDescription
ANTHROPIC_API_KEYstring""API key from Anthropic Console (required for direct Anthropic access)
ANTHROPIC_MAX_RETRIESinteger2Retry attempts; lower default due to Anthropic's robust infrastructure

AWS Bedrock​

For Claude, Llama, Titan, and other models via AWS Bedrock managed service.

ParameterTypeDefaultDescription
AWS_BEDROCK_MAX_RETRIESinteger5Retry attempts for throttled or failed Bedrock API calls
AWS_BEDROCK_READ_TIMEOUTinteger60000Request timeout in milliseconds; increase for long-running generations
AWS_BEDROCK_REGIONstring""AWS region hosting Bedrock service (e.g., us-east-1, us-west-2)

Google Vertex AI​

For Gemini, and Claude via Google Cloud's Vertex AI platform.

ParameterTypeDefaultDescription
GOOGLE_VERTEXAI_REGIONstring""Region for Vertex AI models (e.g., us-central1, europe-west4)
GOOGLE_CLAUDE_VERTEXAI_REGIONstring""Separate region for Claude on Vertex AI if different from main region
GOOGLE_VERTEXAI_MAX_RETRIESinteger5Retry attempts for rate-limited or failed Vertex AI requests
GOOGLE_PROJECT_IDstring""GCP project ID where Vertex AI is enabled
GOOGLE_REGIONstring""Default GCP region for all Google services
GCP_API_KEYstring""Base64-encoded service account JSON key for GCP authentication; not recommended for production — use Workload Identity instead to avoid storing long-lived credentials
VERTEX_AI_ANTHROPIC_ENABLE_PROMPT_CACHEbooleanfalseEnable Anthropic prompt-caching headers when calling Claude models via Vertex AI; set to true only when the Vertex AI endpoint has confirmed support for caching headers

Additional AI Service Integrations​

Additional AI services for multimodal capabilities beyond text generation.

Image Generation​

Enables AI-generated images for visual content creation within assistants.

ParameterTypeDefaultDescription
IMAGE_GENERATION_MODELstringgemini-3.1-flash-imageModel used for AI image generation

Speech-to-Text (STT)​

Converts voice input to text for conversational interfaces and voice commands.

ParameterTypeDefaultDescription
STT_API_URLstring""Whisper or compatible STT service endpoint
STT_API_KEYstring""Authentication key for STT service
STT_API_DEPLOYMENT_NAMEstring""Azure-specific deployment identifier if using Azure Speech
STT_MODEL_NAMEstring""Model variant (e.g., whisper-1) to use for transcription

Azure Speech Services​

Microsoft's speech-to-text and text-to-speech services for Azure deployments.

ParameterTypeDefaultDescription
AZURE_SPEECH_REGIONstring""Azure region for Speech resource (e.g., eastus, westeurope)
AZURE_SPEECH_SERVICE_KEYstring""Subscription key from Azure Speech resource

Database Configuration​

Configure persistent data storage for conversations, users, workflows, and application state.

PostgreSQL​

Primary relational database for structured data and transactional operations.

ParameterTypeDefaultDescription
POSTGRES_HOSTstring"localhost"PostgreSQL server hostname or IP address
POSTGRES_PORTinteger5432PostgreSQL server port
POSTGRES_DBstring"postgres"Database name for CodeMie tables and data
POSTGRES_USERstring"postgres"Database username with read/write permissions
POSTGRES_PASSWORDstring"password"Database password (use secrets manager in production)
PG_URLstring""Complete connection string (overrides individual params if set)
PG_POOL_SIZEinteger10Connection pool size; increase for high concurrency workloads
DEFAULT_DB_SCHEMAstring"codemie"PostgreSQL schema for organizing CodeMie tables
PG_IAM_AUTH_PROVIDERstring ("", gcp, aws, azure)""Enables cloud IAM token-based authentication for PostgreSQL instead of a static password; when set, POSTGRES_PASSWORD is ignored and a short-lived token is fetched from the matching cloud provider
PG_AWS_RDS_REGIONstring""AWS region used when generating an RDS IAM auth token (PG_IAM_AUTH_PROVIDER=aws); falls back to AWS_DEFAULT_REGION when empty

Elasticsearch​

Document store for full-text search, analytics, and unstructured data.

ParameterTypeDefaultDescription
ELASTIC_URLstring"http://localhost:9200"Elasticsearch cluster endpoint URL
ELASTIC_PASSWORDstring""Password for elastic user or configured username
ELASTIC_USERNAMEstring""Username for Elasticsearch authentication
ELASTIC_DATASOURCE_REPLICASinteger1Number of replica shards for datasource indexes; set to 0 to have only the primary shard for each indexed datasource, reducing total shard usage on clusters with limited capacity

Elasticsearch Indexes​

Index names for different data types. Customize to avoid collisions in shared clusters.

ParameterTypeDefaultDescription
ELASTIC_APPLICATION_INDEXstring"applications"Indexed applications and their metadata
ELASTIC_GIT_REPO_INDEXstring"repositories"Code repository metadata and indexing status
ELASTIC_LOGS_INDEXstring"logs-codemie-infra*"Infrastructure logs pattern for monitoring and debugging
ELASTIC_METRICS_INDEXstring"codemie_metrics_logs*"Index pattern used by the analytics repository for all ES|QL queries and dashboard aggregations; changing this redirects the entire analytics dashboard to a different index or alias
FEEDBACK_INDEX_NAMEstring"ca_feedback"User feedback and ratings on AI responses
BACKGROUND_TASKS_INDEXstring"background_tasks"Async task queue and execution status
USER_CONVERSATION_INDEXstring"codemie_raw_user_conversations"Complete conversation history and messages
USER_CONVERSATION_FOLDER_INDEXstring"codemie_conversation_folder"Folder organization for conversation management
CONVERSATIONS_METRICS_INDEXstring"codemie_conversation_metrics"Analytics data on conversation usage and performance
SHARED_CONVERSATION_INDEXstring"codemie_shared_conversations"Conversations shared across users or teams
ASSISTANTS_INDEXstring"codemie_assistants"Assistant definitions, configurations, and templates
WORKFLOWS_INDEXstring"workflows"Workflow definitions and templates
SETTINGS_INDEXstring"codemie_user_settings"User preferences and personalization data
USER_DATA_INDEXstring"codemie_user_data"Additional user-related data and metadata
INDEX_STATUS_INDEXstring"index_status"Status tracking for repository and datasource indexing
PROVIDERS_INDEXstring"providers"AI provider configurations and availability
WORKFLOW_EXECUTION_INDEXstring"workflows_execution_history"Historical workflow runs and outcomes
WORKFLOW_EXECUTION_STATE_INDEXstring"workflows_execution_states"Current state of running workflows
WORKFLOW_EXECUTION_STATE_THOUGHTS_INDEXstring"workflows_execution_state_thoughts"Workflow reasoning and decision logs
TOOLS_INDEX_NAMEstring"codemie_tools"Semantic index for intelligent tool selection

File Storage Configuration​

Configure where and how CodeMie stores uploaded files, attachments, and generated content.

General Storage Settings​

ParameterTypeDefaultDescription
FILES_STORAGE_TYPEstring"filesystem"Storage backend: filesystem (local on pod), aws (S3), azure (blob), gcp (bucket)
FILES_STORAGE_DIRstring"./codemie-storage"Local directory path when using filesystem storage type
FILES_STORAGE_MAX_UPLOAD_SIZEinteger104857600Maximum file size in bytes (100 MB default); increase for large document processing
REPOS_LOCAL_DIRstring"./codemie-repos"Directory for cloned Git repositories during code indexing
IMAGE_INDEXING_MAX_SIZE_BYTESinteger10485760Maximum image file size in bytes (10 MB) during datasource indexing; files exceeding this limit are skipped

Cloud Storage - AWS S3​

Configuration for Amazon S3 storage backend (requires FILES_STORAGE_TYPE=aws).

ParameterTypeDefaultDescription
AWS_DEFAULT_REGIONstring""AWS region. Must be set if AWS_S3_REGION or AWS_KMS_REGION are not configured
AWS_S3_REGIONstringAWS_DEFAULT_REGIONS3-specific region override. When set, takes priority over AWS_DEFAULT_REGION for S3 operations
AWS_S3_BUCKET_NAMEstring""S3 bucket name for user files and attachments
CODEMIE_STORAGE_BUCKET_NAMEstring"codemie-global-storage"Bucket for system-level shared assets and resources

Cloud Storage - Azure Blob​

Configuration for Azure Blob Storage backend (requires FILES_STORAGE_TYPE=azure).

ParameterTypeDefaultDescription
AZURE_STORAGE_CONNECTION_STRINGstring""Complete connection string from Azure Storage account
AZURE_STORAGE_ACCOUNT_NAMEstring""Storage account name for alternative authentication methods

Cloud Storage - GCP​

Configuration for Google Cloud Storage backend (requires FILES_STORAGE_TYPE=gcp).

ParameterTypeDefaultDescription
FILES_STORAGE_GCP_REGIONstring"US"Multi-region or region for Cloud Storage buckets

Redis Configuration​

ParameterTypeDefaultDescription
REDIS_HOSTstringlocalhostRedis endpoint address
REDIS_PORTint6379Remote port
REDIS_PASSWORDstring""Authentication secret for default user
REDIS_DBint0Redis database ID
REDIS_SSLboolFalseEnforce SSL connection to the remote endpoint
REDIS_SSL_CERT_REQSstringnoneRequire valid certificates from endpoint. Valid values: none, optional, required
REDIS_CONNECT_TIMEOUT_SECONDSfloat5.0Connection timeout
REDIS_TIMEOUT_SECONDSfloat5.0Socket timeout for regular operations

Security & Encryption​

Encryption Configuration​

Protect sensitive data at rest using cloud key management services or HashiCorp Vault.

ParameterTypeDefaultDescription
ENCRYPTION_TYPEstring"plain"Encryption method: plain (none), aws (KMS), azure (Key Vault), gcp (Cloud KMS), vault (HashiCorp Vault with Transit Engine)

AWS KMS​

Encrypt secrets and sensitive data using AWS Key Management Service.

ParameterTypeDefaultDescription
AWS_KMS_KEY_IDstring""KMS key ID or ARN for encryption/decryption operations
AWS_KMS_REGIONstringAWS_DEFAULT_REGIONKMS-specific region override. When set, takes priority over AWS_DEFAULT_REGION for KMS operations

Azure Key Vault​

Encrypt data using Azure Key Vault's encryption keys and secrets management.

ParameterTypeDefaultDescription
AZURE_KEY_VAULT_URLstring""Key Vault URL (e.g., https://mykeyvault.vault.azure.net/)
AZURE_KEY_NAMEstring""Name of encryption key within Key Vault
AZURE_SUBSCRIPTION_IDstring""Azure subscription ID for service principal authentication
AZURE_TENANT_IDstring""Azure AD tenant ID for authentication
AZURE_CLIENT_IDstring""Service principal application (client) ID
AZURE_CLIENT_SECRETstring""Service principal secret for authentication

GCP KMS​

Encrypt data using Google Cloud Key Management Service.

ParameterTypeDefaultDescription
GOOGLE_KMS_PROJECT_IDstringUses GOOGLE_PROJECT_IDGCP project containing KMS resources
GOOGLE_KMS_KEY_RINGstring"codemie"Key ring grouping encryption keys
GOOGLE_KMS_CRYPTO_KEYstring"codemie"Specific crypto key for encryption operations
GOOGLE_KMS_REGIONstringUses GOOGLE_REGIONRegion where KMS key ring is located

HashiCorp Vault​

Encrypt data using Vault's Transit secrets engine for centralized key management.

ParameterTypeDefaultDescription
VAULT_URLstring""Vault server URL (e.g., https://vault.company.com:8200)
VAULT_TOKENstring""Authentication token with transit engine permissions
VAULT_NAMESPACEstring""Vault namespace for multi-tenant deployments
VAULT_TRANSIT_KEY_NAMEstring"codemie"Transit engine key name for encryption
VAULT_TRANSIT_MOUNT_POINTstring"transit"Mount path for Transit secrets engine

Identity & Access Management​

Configure authentication providers and access control for users and administrators.

IDP Configuration​

ParameterTypeDefaultDescription
IDP_PROVIDERstring"local"Identity provider: keycloak (recommended), local (for development)
KEYCLOAK_LOGOUT_URLstring""Keycloak logout endpoint for proper session termination
ADMIN_USER_IDstring""User ID to automatically grant admin privileges on startup
ADMIN_ROLE_NAMEstring"admin"Role name identifying administrators in the system

User Management Mode​

Controls whether user roles and project access are read from JWT claims (Keycloak-managed mode) or stored in the platform database (Platform-managed mode). See Access Control Overview for a full comparison.

For step-by-step instructions on enabling Platform-managed mode and migrating existing Keycloak users, see Platform-managed Mode Configuration.

ParameterTypeDefaultDescription
ENABLE_USER_MANAGEMENTboolfalseMaster switch. true enables Platform-managed mode: roles and project membership are stored in the platform DB and managed through the in-app UI. false uses Keycloak-managed mode where JWT claims are the authoritative source.
USER_PROJECT_LIMITint3Maximum number of shared projects a regular user can be assigned to. Enforced only when ENABLE_USER_MANAGEMENT=true. Super Admins always have unlimited access.

Keycloak User Migration​

Required only when ENABLE_USER_MANAGEMENT=true and IDP_PROVIDER=keycloak. Enables a one-time import of existing Keycloak users and their project attributes into the platform database on startup.

ParameterTypeDefaultDescription
KEYCLOAK_MIGRATION_ENABLEDboolfalseEnables the one-time import of Keycloak users into the platform database. Run once during initial migration; disable after the import completes.
KEYCLOAK_ADMIN_URLstring""Keycloak base URL for admin API access (e.g., https://keycloak.example.com).
KEYCLOAK_ADMIN_REALMstring""Keycloak realm to migrate (e.g., codemie-prod).
KEYCLOAK_ADMIN_CLIENT_IDstring""Service account client ID with Keycloak admin permissions.
KEYCLOAK_ADMIN_CLIENT_SECRETstring""Service account client secret.
KEYCLOAK_MIGRATION_BATCH_SIZEinteger100Number of Keycloak users fetched per paginated API call; smaller values reduce memory pressure during large migrations.
KEYCLOAK_MIGRATION_LOCK_TIMEOUT_MINUTESinteger30Age threshold after which a migration lock held by another pod is considered stale and may be taken over; prevents deadlocks when a pod crashes.
KEYCLOAK_MIGRATION_WAIT_INTERVAL_SECONDSinteger5How long a follower pod sleeps between polls while waiting for the leader pod to finish the migration.

Admin Bootstrap​

Auto-create a SuperAdmin account on startup when none exists. Active only when IDP_PROVIDER=local and ENABLE_USER_MANAGEMENT=true in non-local environments.

ParameterTypeDefaultDescription
SUPERADMIN_EMAILstring""Email for the auto-created SuperAdmin; both fields must be set to trigger bootstrap
SUPERADMIN_PASSWORDstring""Password for the auto-created SuperAdmin; both fields must be set to trigger bootstrap

Local Authentication (JWT)​

Used only when IDP_PROVIDER=local. Keys are auto-generated on first startup if the files do not exist.

ParameterTypeDefaultDescription
JWT_ALGORITHMstring"RS256"Algorithm used to sign and verify local-auth JWTs; changing this requires regenerating the key files
JWT_EXPIRATION_HOURSinteger24Lifetime of locally-issued access tokens in hours
JWT_PRIVATE_KEY_PATHstring".keys/jwt_private.pem"Path to the RSA private key PEM file used to sign tokens
JWT_PUBLIC_KEY_PATHstring".keys/jwt_public.pem"Path to the RSA public key PEM file used to verify tokens
JWT_ISSUERstring"codemie-local"Value of the iss claim in every locally-issued JWT; tokens with a mismatched issuer are rejected with HTTP 401

JWKS Signature Validation​

Optional defense-in-depth layer that cryptographically verifies inbound bearer JWTs against trusted issuers' JWKS endpoints before any IDP claim extraction.

ParameterTypeDefaultDescription
JWKS_VALIDATION_ENABLEDbooleanfalseWhen true, wraps the active IDP with a JWKS-validating layer; every inbound JWT is verified against the configured trusted issuers
JWKS_TRUSTED_ISSUERSstring""JSON array of {issuer, audience, jwks_uri?, discovery_url?} objects; required when JWKS_VALIDATION_ENABLED=true
JWKS_CACHE_TTL_SECONDSinteger300How long fetched public key sets are cached in memory before a fresh fetch from the issuer's endpoint
JWKS_HTTP_TIMEOUT_SECONDSfloat3.0Per-request HTTP timeout when fetching JWKS or OIDC discovery documents from trusted issuers
JWKS_LEEWAY_SECONDSinteger30Clock-skew tolerance applied when verifying JWT exp and nbf claims

Session cookie settings for the local-auth login flow. Only relevant when IDP_PROVIDER=local.

ParameterTypeDefaultDescription
RATE_LIMIT_LOGINstring"5/15minutes"Slowdown rate for the login endpoint expressed as "<count>/<period>"; exceeding it returns HTTP 429 to prevent credential-stuffing
AUTH_COOKIE_NAMEstring"codemie_access_token"Name of the HTTP cookie that carries the access token to browsers
AUTH_COOKIE_HTTPONLYbooleantrueSets HttpOnly on the auth cookie; prevents JavaScript from reading it, reducing XSS token-theft risk
AUTH_COOKIE_SECUREbooleanfalseSets Secure on the auth cookie so browsers transmit it over HTTPS only; must be true in production
AUTH_COOKIE_SAMESITEstring (lax, strict, none)"lax"SameSite attribute controlling cross-site request inclusion; use strict for maximum CSRF protection
AUTH_COOKIE_PATHstring"/"Cookie Path attribute; narrowing this prevents the cookie from being sent to unrelated endpoints
AUTH_TOKEN_CACHE_MAX_SIZEinteger10000Maximum entries in the in-memory cache that maps validated tokens to user objects, avoiding repeated database lookups
AUTH_TOKEN_CACHE_TTLinteger30TTL in seconds for cached token-to-user mappings; shorter values shrink the window where a revoked token is still accepted

Email & Password (Local Auth)​

SMTP configuration for sending verification and password-reset emails. Only active when IDP_PROVIDER=local.

ParameterTypeDefaultDescription
EMAIL_VERIFICATION_ENABLEDbooleantrueWhen true, new users must verify their email before logging in; set false to auto-verify all accounts
EMAIL_SMTP_HOSTstring""SMTP server hostname; leave empty to disable email sending entirely
EMAIL_SMTP_PORTinteger587SMTP server port
EMAIL_SMTP_USERNAMEstring""SMTP account username
EMAIL_SMTP_PASSWORDstring""SMTP account password
EMAIL_FROM_ADDRESSstring""From: address for outbound emails; must be set for email delivery to be active
EMAIL_FROM_NAMEstring"CodeMie"Display name shown alongside EMAIL_FROM_ADDRESS in email clients
EMAIL_USE_TLSbooleantrueUse STARTTLS upgrade on the configured port; set false for servers using implicit TLS or no TLS
FRONTEND_URLstring"http://localhost:3000"Base URL of the frontend, used to build clickable verification and password-reset links in emails
PASSWORD_MIN_LENGTHinteger12Minimum character length for passwords; shorter passwords are rejected with HTTP 400

Cost Center​

ParameterTypeDefaultDescription
COST_CENTER_NAME_PATTERNstring"^[a-z0-9]+-[a-z0-9]+$"Regex applied via re.fullmatch to every cost-center name at creation or update time; names not matching are rejected

Broker Token Exchange​

Multi-hop Keycloak token exchange chain. Activated automatically when BROKER_TOKEN_URLS is non-empty.

ParameterTypeDefaultDescription
BROKER_TOKEN_URLSstring""Comma-separated base URLs for each hop in the exchange chain; must have the same length as BROKER_TOKEN_REALMS and BROKER_TOKEN_BROKERS
BROKER_TOKEN_REALMSstring""Comma-separated realm names, one per hop
BROKER_TOKEN_BROKERSstring""Comma-separated broker identifiers, one per hop
BROKER_TOKEN_TIMEOUTfloat5.0Per-hop HTTP request timeout in seconds
BROKER_AUTH_LOCATION_URLstring""Value placed in the x-user-mcp-auth-location response header when a broker exchange step returns an auth failure

OIDC Token Exchange​

Swaps a user's current access token for an audience-scoped token required by an MCP server, using a Keycloak or Okta token endpoint.

ParameterTypeDefaultDescription
TOKEN_EXCHANGE_URLstring""OAuth 2.0 token endpoint URL; leave empty to disable OIDC token exchange
TOKEN_EXCHANGE_GRANT_TYPEstring"urn:ietf:params:oauth:grant-type:token-exchange"OAuth 2.0 grant_type sent to the exchange endpoint; rarely needs changing
TOKEN_EXCHANGE_CLIENT_IDstring""OAuth 2.0 client ID for the token exchange service account
TOKEN_EXCHANGE_CLIENT_SECRETstring""OAuth 2.0 client secret for the token exchange service account
TOKEN_EXCHANGE_SUBJECT_TOKEN_TYPEstring"urn:ietf:params:oauth:token-type:access_token"subject_token_type parameter sent with the exchange request
TOKEN_EXCHANGE_TIMEOUTfloat5.0HTTP request timeout in seconds for each token exchange call
TOKEN_EXCHANGE_SERVICEstring"keycloak"Credential encoding: keycloak sends credentials in the POST body; okta uses HTTP Basic Authorization

External User Configuration​

Control access for external users (e.g., contractors, partners) with limited permissions.

ParameterTypeDefaultDescription
EXTERNAL_USER_TYPEstring"external"User type identifier for external user classification
EXTERNAL_USER_ALLOWED_PROJECTSlist[string]["codemie"]Projects accessible to external users for collaboration

Integration Services​

Connect CodeMie to external services for enhanced tools capabilities.

Search Services​

Enable web search capabilities for assistants to access current information.

ParameterTypeDefaultDescription
GOOGLE_SEARCH_API_KEYstring""API key for Google Custom Search integration. Can be registered in the GCP account
GOOGLE_SEARCH_CSE_IDstring""Custom Search Engine ID for scoped web searches. Can be registered here https://programmablesearchengine.google.com/controlpanel/all
TAVILY_API_KEYstring""Tavily API key for AI-optimized web search and extraction

Kubernetes Integration​

Enable deployment, monitoring, and management of Kubernetes resources via assistants.

ParameterTypeDefaultDescription
KUBERNETES_API_URLstring""Kubernetes API server URL (typically in-cluster or external endpoint)
KUBERNETES_API_TOKENstring""Service account token with appropriate RBAC permissions

Version Control Systems​

Configure Git provider detection for repository indexing and code analysis.

ParameterTypeDefaultDescription
GITHUB_IDENTIFIERSlist[string]["github"]URL patterns identifying GitHub repositories
GITLAB_IDENTIFIERSlist[string]["gitlab"]URL patterns identifying GitLab repositories
BITBUCKET_IDENTIFIERSlist[string]["bitbucket"]URL patterns identifying Bitbucket repositories
AZURE_DEVOPS_REPOS_IDENTIFIERSlist[string]["dev.azure.com"]URL patterns identifying Azure DevOps repositories

SharePoint OAuth​

Enable delegated authentication for SharePoint datasources using Authorization Code + PKCE flow.

ParameterTypeDefaultDescription
SHAREPOINT_PKCE_ENABLEDbooleanfalseEnable Authorization Code + PKCE flow for SharePoint OAuth. Requires SHAREPOINT_OAUTH_CLIENT_ID and a matching Azure AD app registration.
SHAREPOINT_OAUTH_CLIENT_IDstring""Azure AD application (client) ID used for SharePoint OAuth authorization.
SHAREPOINT_OAUTH_SCOPESstring"Sites.Read.All Files.Read.All offline_access User.Read"Space-separated OAuth scopes requested during authorization.
Redis Required

SharePoint PKCE flow stores OAuth state and tokens in Redis during the authorization handshake. A running Redis instance must be configured (see Redis Configuration) before enabling SHAREPOINT_PKCE_ENABLED.

Azure AD Setup

The redirect URI registered in the Azure AD app must match:

{CALLBACK_API_BASE_URL}{API_ROOT_PATH}/v1/sharepoint/oauth/callback

Use the Web platform type in Azure AD app registration. Also enable the customer feature flag features:sharepointCodeMieOAuth to show the "Sign in with Microsoft" button in the SharePoint datasource setup UI.

Google OAuth​

Enable delegated Google authentication for Google Docs datasources using Authorization Code + PKCE flow.

ParameterTypeDefaultDescription
GOOGLE_OAUTH_CLIENT_IDstring""OAuth 2.0 Client ID from Google Cloud Console.
GOOGLE_OAUTH_CLIENT_SECRETstring""OAuth 2.0 Client Secret from Google Cloud Console.
Redis Required

The Google OAuth flow stores PKCE state and tokens in Redis during the authorization handshake. A running Redis instance must be configured (see Redis Configuration) before enabling Google OAuth.

Google Cloud Console Setup
  1. Create an OAuth 2.0 Client ID (application type: Web application) in Google Cloud Console under APIs & Services → Credentials.
  2. Register the following Authorized Redirect URI: 
    {CALLBACK_API_BASE_URL}{API_ROOT_PATH}/v1/google-oauth/callback
    CALLBACK_API_BASE_URL is documented in Callback Configuration. API_ROOT_PATH defaults to /code-assistant-api in Helm deployments.
  3. Enable these APIs under APIs & Services → Library: Google Docs API.

NATS Message Broker Configuration​

Configure NATS for plugin communication, event streaming, and distributed messaging.

Connection Settings​

ParameterTypeDefaultDescription
NATS_SERVERS_URIstring"nats://nats:4222"NATS server cluster URI; supports multiple comma-separated servers
NATS_CLIENT_CONNECT_URIstring""Alternative client connection URI if different from server URI
NATS_USERstring"codemie"Username for NATS authentication
NATS_PASSWORDstring"codemie"Password for NATS authentication (use secrets in production)
NATS_SKIP_TLS_VERIFYbooleanfalseSkip TLS certificate validation (only for development/testing)
NATS_CONNECT_TIMEOUTinteger5Connection establishment timeout in seconds

Connection Behavior​

ParameterTypeDefaultDescription
NATS_MAX_RECONNECT_ATTEMPTSinteger-1Max reconnection attempts (-1 for unlimited retries with backoff)
NATS_RECONNECT_TIME_WAITinteger10Seconds to wait between reconnection attempts
NATS_MAX_OUTSTANDING_PINGSinteger5Max unanswered pings before connection considered dead
NATS_PING_INTERVALinteger120Seconds between keepalive pings to detect connection issues
NATS_VERBOSEbooleanfalseEnable detailed NATS protocol logging for debugging

Connection Pool​

Optimize NATS performance with connection pooling for high-throughput scenarios.

ParameterTypeDefaultDescription
NATS_CONNECTION_POOL_SIZEinteger20Number of NATS connections to maintain in pool
NATS_CONNECTION_POOL_MAX_AGEinteger300Max connection age in seconds before recycling
NATS_CONNECTION_POOL_ACQUIRE_TIMEOUTfloat10.0Max seconds to wait for available connection from pool

Plugin Configuration​

Configure NATS-based plugin system for extending CodeMie capabilities.

ParameterTypeDefaultDescription
NATS_PLUGIN_KEY_CHECK_ENABLEDbooleanfalseValidate plugin authentication keys before allowing execution
NATS_PLUGIN_PING_TIMEOUT_SECONDSinteger1Max seconds to wait for plugin health check response
NATS_PLUGIN_UPDATE_INTERVALinteger60Seconds between plugin availability refresh checks
NATS_PLUGIN_LIST_TIMEOUT_SECONDSinteger15Max seconds to wait for plugin discovery responses
NATS_PLUGIN_MAX_VALIDATION_ATTEMPTSinteger3Max attempts to validate plugin before marking unavailable
NATS_PLUGIN_V2_ENABLEDbooleantrueEnable enhanced plugin protocol v2 with improved features
NATS_PLUGIN_TOOL_TIMEOUTinteger302Max seconds for plugin tool execution (5 min + buffer)
NATS_PLUGIN_EXECUTE_TIMEOUTinteger302Max seconds for plugin command execution

MCP (Model Context Protocol) Configuration​

Configure Model Context Protocol for enhanced AI context management and tool integration.

MCP Connect​

ParameterTypeDefaultDescription
MCP_CONNECT_ENABLEDbooleantrueEnable MCP functionality for advanced context handling
MCP_CONNECT_URLstring"http://localhost:3000"MCP server endpoint for context coordination
MCP_CONNECT_BUCKETS_COUNTinteger10Number of context buckets for partitioning and isolation
MCP_TOOL_TOKENS_SIZE_LIMITinteger30000Max tokens for tool definitions to prevent context overflow

MCP Client Configuration​

ParameterTypeDefaultDescription
MCP_CLIENT_TIMEOUTfloat300.0Max seconds for MCP operations (5 minutes for complex contexts)

MCP Caching​

Improve MCP performance by caching toolkit instances and reducing initialization overhead.

ParameterTypeDefaultDescription
MCP_TOOLKIT_SERVICE_CACHE_SIZEinteger100Max cached toolkit instances to retain in memory
MCP_TOOLKIT_SERVICE_CACHE_TTLinteger3600Toolkit cache lifetime in seconds (1 hour)
MCP_TOOLKIT_FACTORY_CACHE_SIZEinteger50Max cached toolkit factories to retain
MCP_TOOLKIT_FACTORY_CACHE_TTLinteger600Factory cache lifetime in seconds (10 minutes)

MCP Header Propagation​

Control which HTTP headers are forwarded to downstream services (MCP servers, providers) for security and privacy.

ParameterTypeDefaultDescription
FORWARDED_HEADERS_BLOCKLISTstring"authorization,cookie,set-cookie,x-api-key,x-auth-token,x-internal-secret,x-internal-token"Comma-separated header names (case-insensitive) to block from forwarding to downstream services; prevents credential leakage to MCP servers and providers

MCP Token Cache​

ParameterTypeDefaultDescription
TOKEN_CACHE_TTLinteger600Lifetime in seconds for cached exchanged tokens (10 minutes)
TOKEN_CACHE_MAX_SIZEinteger1024Max total entries across all token caches (per-user and per-audience combined)

MCP Auth Configuration​

Configure MCP OAuth2 authorization server integration for secure MCP client authentication and token management.

MCP Auth Core​

ParameterTypeDefaultDescription
MCP_AUTH_ENABLEDbooleanfalseEnable MCP OAuth2 authorization server; required for MCP clients that need delegated access to external services
MCP_AUTH_HMAC_SECRETstring""HMAC secret for signing MCP auth state tokens; set a strong random value in production

MCP Auth Security​

ParameterTypeDefaultDescription
MCP_AUTH_REDIS_KEY_NAMESPACEstring"codemie:mcp_auth"Redis key namespace prefix for all MCP auth stores; must not end with :
MCP_AUTH_ENFORCE_HTTPSbooleantrueEnforce HTTPS for all MCP auth redirect and callback URLs; disable only in development
MCP_AUTH_ALLOW_LOCAL_CLIENT_METADATA_URLbooleanfalseAllow localhost URLs for MCP client metadata discovery; enable only for local development

MCP Auth Discovery​

ParameterTypeDefaultDescription
MCP_AUTH_DISCOVERY_CONCURRENCY_LIMITinteger5Max concurrent MCP authorization server metadata discovery requests
MCP_AUTH_AS_METADATA_DISCOVERY_TIMEOUT_SECONDSfloat30.0Timeout in seconds for authorization server metadata discovery requests
MCP_AUTH_DCR_REGISTRATION_TIMEOUT_SECONDSfloat30.0Timeout in seconds for dynamic client registration (DCR) requests
MCP_AUTH_DISCOVERY_PROBE_OVERALL_TIMEOUT_SECONDSfloat30.0Overall timeout in seconds for the full discovery probe sequence
MCP_AUTH_RESOURCE_METADATA_DISCOVERY_TIMEOUT_SECONDSfloat30.0Timeout in seconds for protected resource metadata discovery

MCP Auth Token Management System (TMS)​

Enterprise-grade PostgreSQL-backed token storage with KMS encryption. Replaces the default in-memory mock TMS.

ParameterTypeDefaultDescription
MCP_AUTH_TMS_ENABLEDbooleanfalseEnable PostgreSQL-backed enterprise TMS instead of the in-memory mock; required for production deployments
MCP_AUTH_TMS_KMS_KEY_IDstring""KMS key ID for envelope encryption of stored credentials; required when TMS is enabled
MCP_AUTH_TMS_REFRESH_TIMEOUT_SECONDSfloat2.5OAuth2 token refresh timeout in seconds; enterprise validation requires a value between 0 and 3
MCP_AUTH_TMS_REDIS_LOCK_ENABLEDbooleantrueEnable Redis refresh locks to prevent duplicate refresh storms across clustered backend instances
MCP_AUTH_TMS_REDIS_LOCK_TTL_SECONDSinteger10Refresh lock TTL in seconds; must be greater than MCP_AUTH_TMS_REFRESH_TIMEOUT_SECONDS
MCP_AUTH_TMS_AUDIT_REQUIREDbooleantrueRequire a durable audit write to complete before credential operations return successfully
MCP_AUTH_TMS_AUDIT_FALLBACK_ENABLEDbooleanfalseEnable a durable fallback audit sink when the primary audit write path is unavailable
MCP_AUTH_TMS_AUDIT_SANITIZE_DIAGNOSTICSbooleantrueSanitize sensitive diagnostic details from audit records before storage
MCP_AUTH_TMS_ALLOW_MOCKbooleanfalseAllow in-memory mock TMS in non-production environments when real TMS is disabled; never enable in production

Webhook Rate Limiting​

Protect webhook endpoints with Redis-backed fixed-window rate limiting.

ParameterTypeDefaultDescription
WEBHOOK_RATE_LIMIT_ENABLEDbooleantrueEnable rate limiting on incoming webhook requests
WEBHOOK_RATE_LIMIT_MAX_REQUESTSinteger10Max webhook requests allowed per time window per client
WEBHOOK_RATE_LIMIT_WINDOW_SECONDSinteger60Rate limit time window in seconds
WEBHOOK_RATE_LIMIT_REDIS_KEY_NAMESPACEstring"codemie:webhook_rate_limit"Redis key namespace prefix for rate limit counters

LLM Proxy & LiteLLM Configuration​

✨Enterprise Feature

This is an enterprise feature.

Configure LiteLLM proxy for unified LLM access, budget management, and usage tracking.

Proxy Mode​

ParameterTypeDefaultDescription
LLM_PROXY_MODEstring"internal"Proxy mode: internal (built-in routing), lite_llm (external LiteLLM proxy)
LLM_PROXY_ENABLEDbooleanfalseEnable LLM proxy for centralized model access control
LLM_PROXY_TIMEOUTinteger300Max seconds to wait for proxy responses
LLM_PROXY_EMBEDDINGS_DISABLEDbooleanfalseWhen true, bypasses the LiteLLM proxy for embedding requests and sends them directly to the native provider (e.g., Azure OpenAI). Useful when LiteLLM does not support a required embedding model or when lower-latency direct access is preferred for vector operations. Has no effect when LLM_PROXY_ENABLED=false or LLM_PROXY_MODE=internal.
LLM_PROXY_LANGFUSE_TRACESbooleanfalseEnable Langfuse tracing for requests going through the LiteLLM proxy
LLM_PROXY_TRACK_USAGEbooleantrueTrack token usage for requests going through the LiteLLM proxy; disable to skip usage recording
LLM_PROXY_SHARED_ASSET_PROJECT_BUDGET_ROUTING_ENABLEDbooleantrueRoute requests for shared assets (assistants, workflows not owned by a personal project) to the project budget instead of the user's personal budget

LiteLLM Connection​

Connect to external LiteLLM proxy for advanced features like load balancing and fallbacks.

ParameterTypeDefaultDescription
LITE_LLM_URLstring""LiteLLM proxy server URL (e.g., http://litellm:4000)
LITE_LLM_APP_KEYstring""Application-specific key for LiteLLM authentication
LITE_LLM_MASTER_KEYstring""Master key for LiteLLM administrative operations
LITE_LLM_PROXY_APP_KEYstring""Optional API key for proxy endpoints used by coding agents; falls back to LITE_LLM_APP_KEY if empty

LiteLLM Model Tagging​

Tag LLM requests for cost tracking and usage analytics.

ParameterTypeDefaultDescription
LITE_LLM_PROJECTS_TO_TAGS_LISTstring""Comma-separated project names to include as request tags
LITE_LLM_TAGS_HEADER_VALUEstring"default"Default tag value when project doesn't match configured list

LiteLLM Budget Configuration​

Set spending limits per user or team to control LLM usage costs.

ParameterTypeDefaultDescription
LLM_PROXY_BUDGET_CHECK_ENABLEDbooleanfalseEnables LLM budget enforcement. When true, CodeMie actively enforces spending limits - requests from users or projects that have exceeded their budget are blocked. Also enables budget API routes and background budget maintenance. budgets-config.yaml defines predefined budgets; set LLM_PROXY_BUDGET_RECONCILIATION_ENABLED=true to sync them into the database and LiteLLM on startup.
LLM_PROXY_BUDGET_RECONCILIATION_ENABLEDbooleanfalseRuns a budget reconciliation job after app readiness to align LiteLLM and CodeMie budget states.
LLM_PROXY_BUDGET_RECONCILIATION_TIMEOUT_SECONDSinteger600Timeout in seconds for a single reconciliation run.
LITELLM_PREMIUM_MODELS_ALIASESlist[string][]List of model name substrings treated as premium (e.g., ["opus", "claude-4"]). Matched case-insensitively against the requested model name. When a match is found, the request is routed to a separate premium_models budget instead of the default platform budget, enabling independent spend tracking and stricter limits for costly models. Required when a premium_models budget category is configured in budgets-config.yaml.
BUDGETS_CONFIG_DIRPathconfig/budgetsDirectory path for the budgets-config.yaml file defining predefined budget policies.

Budget Cache​

Caches user-to-budget resolution results to reduce database load on high-traffic deployments.

ParameterTypeDefaultDescription
BUDGET_ASSIGNMENT_CACHE_TTLinteger60TTL in seconds for the user-to-budget assignment cache (user to category to budget ID mapping).
BUDGET_ASSIGNMENT_CACHE_MAX_SIZEinteger50000Maximum number of entries in the assignment cache.
BUDGET_RESOLUTION_CACHE_TTLinteger60TTL in seconds for the budget resolution cache.
BUDGET_RESOLUTION_CACHE_MAX_SIZEinteger50000Maximum number of entries in the resolution cache.
BUDGET_USAGE_STALENESS_THRESHOLD_MSinteger600000Threshold in milliseconds (10 min) after which budget usage is considered stale and lazily refreshed on the /budget_usage endpoint.

Budget Reset Tracking​

Manages automatic reset of per-member budget windows aligned with LiteLLM's reset cycle.

ParameterTypeDefaultDescription
LITELLM_BUDGET_RESET_TRACKER_ENABLEDbooleanfalseEnables the background job that monitors soon-to-reset project budget windows.
LITELLM_BUDGET_RESET_TRACKER_SCHEDULEstring"*/10 * * * *"Cron schedule (UTC) for the reset-window tracker job. Defaults to every 10 minutes.
LITELLM_BUDGET_RESET_WINDOW_MINUTESinteger15Look-ahead window in minutes for detecting project budgets that will reset soon.
LITELLM_BUDGET_RESET_RECONCILIATION_ENABLEDbooleanfalseEnables the daily reconciliation job that re-syncs reset state at midnight UTC.
LITELLM_BUDGET_RESET_RECONCILIATION_SCHEDULEstring"10 0 * * *"Cron schedule (UTC) for the reset reconciliation job. Must run within LITELLM_BUDGET_RESET_RECONCILIATION_WINDOW_MINUTES of midnight.
LITELLM_BUDGET_RESET_RECONCILIATION_WINDOW_MINUTESinteger10Allowed execution window in minutes after midnight UTC for the reconciliation job.

LiteLLM Spend Tracking​

Configure the background scheduler that collects project-level spending snapshots from LiteLLM and stores them in the project_spend_tracking table. The collector runs automatically for all projects — no per-project filtering configuration is required.

ParameterTypeDefaultDescription
LITELLM_SPEND_COLLECTOR_ENABLEDbooleanfalseEnables the background spend collector job that stores project-level LiteLLM spend snapshots.
LITELLM_SPEND_COLLECTOR_SCHEDULEstring"0 23 * * *"Cron schedule (UTC) for the spend collector. Defaults to nightly at 11 PM (0 23 * * *).

LiteLLM Cache & Optimization​

Reduce latency and API costs by caching metadata and responses.

ParameterTypeDefaultDescription
LITELLM_CUSTOMER_CACHE_TTLinteger300Customer info cache duration in seconds (5 minutes)
LITELLM_USER_CREDENTIALS_CACHE_TTLinteger600User LiteLLM credential lookup cache duration in seconds (10 minutes)
LITELLM_MODELS_CACHE_TTLinteger1800Available models list cache duration in seconds (30 minutes)
LITELLM_REQUEST_TIMEOUTfloat5.0Timeout in seconds for metadata requests to LiteLLM proxy
LITELLM_LIST_REQUEST_TIMEOUTfloat30.0Timeout in seconds for list and bulk endpoints that return larger payloads
LITELLM_FAIL_OPEN_ON_503booleantrueAllow requests when LiteLLM proxy is unavailable (bypass mode on 503 errors)

Agent & Workflow Configuration​

Control AI agent behavior, workflow execution limits, and parallel processing.

AI Agent Settings​

ParameterTypeDefaultDescription
AI_AGENT_RECURSION_LIMITinteger150Max agent reasoning steps to prevent infinite loops
ENABLE_LANGGRAPH_AITOOLS_AGENTbooleantrueUse LangGraph-based agent for advanced tool orchestration
AI_AGENT_CONVERSATION_REPLAY_V2_ENABLEDbooleantrueEnable v2 conversation replay that summarizes older tool turns to reduce token usage

AI Agent History Replay​

Control how previous conversation turns are replayed to the agent to balance context fidelity with token usage.

ParameterTypeDefaultDescription
AI_AGENT_HISTORY_REPLAY_FULL_TOOL_TURNSinteger4Number of most-recent tool turns to include in full (uncompressed) form
AI_AGENT_HISTORY_REPLAY_SUMMARIZED_TOOL_TURNSinteger6Number of older tool turns to include in summarized form before they are dropped

AI Agent History Compaction​

Automatically compress long conversation histories when token usage exceeds a threshold, preserving recent context while summarizing older turns.

ParameterTypeDefaultDescription
AI_AGENT_HISTORY_COMPACTION_ENABLEDbooleanfalseEnable automatic history compaction when conversation exceeds the token limit
AI_AGENT_HISTORY_COMPACTION_TOKEN_LIMITinteger120000Token count that triggers compaction; history is summarized when this threshold is reached
AI_AGENT_HISTORY_COMPACTION_TRIGGER_RATEfloat0.8Fraction of TOKEN_LIMIT at which compaction is triggered (e.g., 0.8 = trigger at 96000 tokens)
AI_AGENT_HISTORY_COMPACTION_TARGET_RATEfloat0.5Fraction of TOKEN_LIMIT to reduce history to after compaction (e.g., 0.5 = target 60000 tokens)
AI_AGENT_HISTORY_COMPACTION_PRESERVE_GROUPSinteger6Number of most-recent conversation groups to preserve verbatim during compaction
AI_AGENT_HISTORY_COMPACTION_BATCH_TOKEN_LIMITinteger24000Max tokens per compaction summary batch; larger batches produce fewer but longer summaries

Workflow Configuration​

ParameterTypeDefaultDescription
WORKFLOW_MAX_CONCURRENCYinteger5Max simultaneous workflow executions to control resource usage
WORKFLOW_DEFAULT_CONCURRENCYinteger2Default concurrency when not specified by workflow
WORKFLOW_GENERATION_ENABLEDbooleanfalseEnable AI-assisted workflow generation feature
WORKFLOW_GENERATOR_LLM_MODELstring""LLM model used for workflow generation; falls back to global default model when empty

Background Jobs​

ParameterTypeDefaultDescription
CRON_SCHEDULER_MAX_WORKERSinteger20Max threads for the background cron scheduler; controls concurrent job capacity

Activity Events​

ParameterTypeDefaultDescription
ACTIVITY_EVENTS_ENABLEDbooleanfalseEnable recording of user activity events for audit and analytics purposes
ACTIVITY_EVENTS_RETENTION_DAYSinteger90Number of days to retain activity event records before automatic cleanup

Trigger Engine​

Enable time-based or event-driven workflow automation.

ParameterTypeDefaultDescription
TRIGGER_ENGINE_ENABLEDbooleanfalseEnable scheduled workflows and event triggers
SCHEDULER_PROMPT_SIZE_LIMITinteger4000Max prompt tokens for scheduled workflow inputs

CodeMie Tools Configuration​

Configure AI tool selection, code analysis integrations, tool execution limits, and tool-specific environment variables for individual CodeMie tool behaviors. These parameters control execution environments, security policies, and feature access for built-in tools.

Code Analysis Tools​

ParameterTypeDefaultDescription
MAX_CODE_TOOLS_OUTPUT_SIZEinteger50000Max characters in code analysis tool output to prevent context overflow

Smart Tool Selection​

Automatically select relevant tools based on user queries to improve response quality.

ParameterTypeDefaultDescription
TOOL_SELECTION_ENABLEDbooleanfalseEnable AI-powered tool selection from available toolkits
TOOL_SELECTION_THRESHOLDinteger3Min tools before triggering smart selection (use all if below)
TOOL_SELECTION_LIMITinteger3Max tools to select per query to optimize token usage

Code Analysis Services​

Integration with advanced code analysis platforms (e.g., AICE).

ParameterTypeDefaultDescription
CODE_ANALYSIS_SERVICE_PROVIDER_NAMEstring"CodeAnalysisServiceProvider"Provider name for code analysis tool integration
CODE_EXPLORATION_SERVICE_PROVIDER_NAMEstring"CodeExplorationServiceProvider"Provider name for code exploration capabilities

Code Executor & Python Sandbox​

Configure secure Python code execution in isolated Kubernetes pods for running user-generated code safely.

ParameterTypeDefaultDescription
CODE_EXECUTOR_ENABLEDbooleanfalseEnable the Code Executor tool. When false, the tool is neither listed in the tools catalog nor executed. Set true to opt in.
CODE_EXECUTOR_EXECUTION_MODEstring"sandbox"Execution mode. Only sandbox is accepted; code always runs in an isolated Kubernetes pod.
CODE_EXECUTOR_SANDBOX_MODEstring"sandbox-shared"Kubernetes sandbox sub-mode: sandbox-shared (reuse a shared pod across sessions — development only) or sandbox-jobs (create a dedicated Job pod per execution — recommended for production; requires gVisor or Kata Containers runtime class in the cluster).
CODE_EXECUTOR_RUNTIME_CLASS_NAMEstring"gvisor"Kubernetes runtimeClassName applied to Job pods when CODE_EXECUTOR_SANDBOX_MODE=sandbox-jobs. Must match an installed runtime class (gvisor or kata-containers).
CODE_EXECUTOR_KUBECONFIG_PATHstring""Path to kubeconfig for Kubernetes authentication (optional, uses in-cluster config if empty). Set to move code execution to a dedicated cluster
CODE_EXECUTOR_WORKDIR_BASEstring"/home/codemie"Base working directory for code execution inside containers
CODE_EXECUTOR_NAMESPACEstring"codemie-runtime"Kubernetes namespace for executor pods
CODE_EXECUTOR_DOCKER_IMAGEstring"codemie/codemie-python:2.41.0"Docker image with Python environment and dependencies for code execution
CODE_EXECUTOR_EXECUTION_TIMEOUTfloat30.0Max seconds for code execution before timeout (prevents infinite loops)
CODE_EXECUTOR_SESSION_TIMEOUTfloat300.0Max session lifetime in seconds before automatic cleanup
CODE_EXECUTOR_DEFAULT_TIMEOUTfloat30.0Default timeout for operations in seconds
CODE_EXECUTOR_MEMORY_LIMITstring"256Mi"Kubernetes memory limit for executor pods
CODE_EXECUTOR_MEMORY_REQUESTstring"256Mi"Kubernetes memory request for executor pods
CODE_EXECUTOR_CPU_LIMITstring"1"Kubernetes CPU limit for executor pods (cores)
CODE_EXECUTOR_CPU_REQUESTstring"100m"Kubernetes CPU request for executor pods (millicores)
CODE_EXECUTOR_EPHEMERAL_STORAGE_LIMITstring"1Gi"Kubernetes ephemeral storage limit for executor pods
CODE_EXECUTOR_EPHEMERAL_STORAGE_REQUESTstring"1Gi"Kubernetes ephemeral storage request for executor pods
CODE_EXECUTOR_MAX_THREADSinteger64Maximum number of threads allowed per execution, enforced inside the sandbox process (both shared and jobs modes).
CODE_EXECUTOR_MAX_OPEN_FILESinteger256Maximum number of open files allowed per execution, enforced inside the sandbox process (both shared and jobs modes). The Python runtime itself opens roughly 20 files before user code runs.
CODE_EXECUTOR_MAX_POD_POOL_SIZEinteger5Max number of executor pods in dynamic pool for concurrent executions
CODE_EXECUTOR_POD_NAME_PREFIXstring"codemie-executor-"Prefix for dynamically created executor pod names
CODE_EXECUTOR_RUN_AS_USERinteger1001Unix user ID for pod security context (non-root execution)
CODE_EXECUTOR_RUN_AS_GROUPinteger1001Unix group ID for pod security context
CODE_EXECUTOR_FS_GROUPinteger1001Filesystem group ID for pod volume permissions
CODE_EXECUTOR_SECURITY_THRESHOLDstring"LOW"Required security policy threshold: SAFE, LOW, MEDIUM, HIGH
CODE_EXECUTOR_YAML_POLICY_PATHstring""Path to custom YAML security policy file (optional, overrides default policy)
CODE_EXECUTOR_VERBOSEbooleanfalseEnable verbose logging for executor debugging
CODE_EXECUTOR_KEEP_TEMPLATEbooleantruePersist pod template after execution for performance optimization
CODE_EXECUTOR_SKIP_ENVIRONMENT_SETUPbooleanfalseSkip environment initialization in sandbox (faster startup but may break dependencies)
Security Considerations

Sandbox Isolation: CODE_EXECUTOR_EXECUTION_MODE=sandbox runs user-supplied code in a dedicated Kubernetes pod, isolated from the CodeMie API. This is the execution model for running untrusted code safely in production.

Security Threshold: The security policy controls what operations are allowed:

  • SAFE (0): Most permissive, blocks almost nothing
  • LOW (1): Allows common operations like HTTP requests (recommended default)
  • MEDIUM (2): More restrictive, blocks potentially dangerous operations
  • HIGH (3): Very restrictive, only allows safe operations

File Datasource Multiprocessing​

Enable parallel processing of file indexing tasks using multiple worker processes.

ParameterTypeDefaultDescription
ENABLE_FILE_MULTIPROCESSINGbooleanfalseEnable multiprocessing for file datasource indexing to speed up large-volume ingestion
FILE_DATASOURCE_MULTIPROCESSING_MAX_WORKERSinteger2Max worker processes for parallel file indexing
FILE_MULTIPROCESSING_MAX_EXECUTED_TASK_PER_WORKERinteger100Max tasks each worker process handles before recycling to prevent memory accumulation

Azure DevOps Integration​

Configuration for Azure DevOps work items, test plans, and wiki integrations.

ParameterTypeDefaultDescription
AZURE_DEVOPS_CACHE_DIRstring""Cache directory for Azure DevOps API responses (empty string disables caching)

Observability & Monitoring​

Track LLM usage, performance metrics, and debugging information.

Langfuse Configuration​

✨Enterprise Feature

This is an enterprise feature.

Send LLM traces to Langfuse for observability, debugging, and prompt optimization.

ParameterTypeDefaultDescription
LANGFUSE_TRACESbooleanfalseEnable detailed LLM tracing (requires Langfuse account)
LANGFUSE_BLOCKED_INSTRUMENTATION_SCOPESlist[string]["elasticsearch-api", "opentelemetry.instrumentation.fastapi", "opentelemetry.instrumentation.sqlalchemy", "opentelemetry.instrumentation.httpx"]Instrumentation scope names excluded from Langfuse tracing to suppress noisy spans
info

When LANGFUSE_TRACES is enabled, the following environment variables (provided by Langfuse) must also be set:

  • LANGFUSE_PUBLIC_KEY - Public API key from Langfuse project
  • LANGFUSE_SECRET_KEY - Secret key for authentication
  • LANGFUSE_HOST - Langfuse instance URL (cloud or self-hosted)

Observability Provider​

Select the active observability backend for distributed tracing. Only one provider is active at a time.

ParameterTypeDefaultDescription
OBSERVABILITY_PROVIDERstring"none"Active tracing backend: none (disabled), langfuse (LLM traces), phoenix (Arize Phoenix), otel (OpenTelemetry)

Phoenix (Arize) Configuration​

Send traces to Arize Phoenix for LLM observability and evaluation. Enable by setting OBSERVABILITY_PROVIDER=phoenix.

ParameterTypeDefaultDescription
PHOENIX_HOSTstring"http://localhost:6006"Phoenix server endpoint URL
PHOENIX_PROJECT_NAMEstring"codemie"Phoenix project name to group traces under
PHOENIX_API_KEYstringnullPhoenix API key for authenticated deployments; omit for local unauthenticated instances
PHOENIX_BATCH_SPAN_PROCESSORbooleantrueUse batch span processor for better throughput; set false for synchronous/debug mode

OpenTelemetry Configuration​

Export traces via OpenTelemetry to any OTLP-compatible backend. Enable by setting OBSERVABILITY_PROVIDER=otel.

ParameterTypeDefaultDescription
OTEL_ENABLEDbooleanfalseEnable OpenTelemetry tracing bootstrap; setting OBSERVABILITY_PROVIDER=otel also requires this
OTEL_EXCLUDED_URLSstring"healthcheck,metrics"Comma-separated URL fragments excluded from tracing to suppress health check and metrics endpoint noise

Prometheus Configuration​

Expose application metrics in Prometheus format on a dedicated port.

ParameterTypeDefaultDescription
PROMETHEUS_ENABLEDbooleanfalseEnable Prometheus metrics exposition
PROMETHEUS_ENDPOINTstring"/metrics"HTTP path for the Prometheus metrics scrape endpoint
PROMETHEUS_METRICS_HOSTstring"0.0.0.0"Host address the metrics server binds to
PROMETHEUS_METRICS_PORTinteger9091Port the dedicated metrics server listens on (separate from the API port)

Pyroscope Configuration​

Continuous profiling integration for CPU and memory profiling in production.

ParameterTypeDefaultDescription
PYROSCOPE_ENABLEDbooleanfalseEnable Pyroscope continuous profiling
PYROSCOPE_SERVER_URLstring"http://localhost:4040"Pyroscope server endpoint to send profiling data to
PYROSCOPE_APP_NAMEstring"codemie"Application name label attached to all profiling data
PYROSCOPE_SAMPLE_RATEinteger100Profiling samples per second; lower values reduce overhead
PYROSCOPE_ONCPUbooleantrueEnable CPU profiling via wall-clock sampling
PYROSCOPE_GIL_ONLYbooleanfalseRestrict sampling to GIL-holding threads only; reduces overhead but limits coverage
PYROSCOPE_ENABLE_LOGGINGbooleanfalseEnable Pyroscope internal debug logging
PYROSCOPE_DETECT_SUBPROCESSESbooleanfalseAutomatically profile spawned subprocesses
PYROSCOPE_TAGSstring""Comma-separated key=value tags added to all profiling data for filtering

Memory Profiling​

Track memory usage and identify memory leaks during application runtime using Python's tracemalloc module.

ParameterTypeDefaultDescription
MEMORY_PROFILING_ENABLEDbooleanfalseEnable tracemalloc and psutil based memory profiling
MEMORY_PROFILING_INTERVAL_MINUTESinteger10Interval between automatic snapshots (in minutes)
MEMORY_PROFILING_DETAIL_LEVELstring"file"Detail level: "file" (fast, groups by file) or "line" (slower, shows exact lines)
MEMORY_PROFILING_SNAPSHOT_PREFIXstring"memory_snapshots"Prefix path for snapshot storage location
info

Memory profiling uses Python's built-in tracemalloc module to capture memory allocation snapshots at regular intervals. Available detail levels:

  • file: Faster, groups memory usage by file (recommended for production debugging)
  • line: Slower, shows exact line numbers (use for detailed analysis in development)
warning

Memory profiling adds CPU overhead and should be used cautiously in production environments. The file detail level has lower performance impact compared to line. Consider increasing the interval (e.g., 30-60 minutes) for production use to minimize resource consumption.

Conversation Analysis​

Automated background job that runs LLM-based analysis on completed conversations to extract insights, patterns, and quality signals.

ParameterTypeDefaultDescription
CONVERSATION_ANALYSIS_ENABLEDbooleanfalseEnable the nightly conversation analysis background job
CONVERSATION_ANALYSIS_SCHEDULEstring"0 0 * * *"Cron schedule (UTC) for the analysis job; defaults to midnight daily
CONVERSATION_ANALYSIS_LOOKBACK_DAYSinteger1Analyze conversations that are at least this many days old (avoids in-progress conversations)
CONVERSATION_ANALYSIS_BATCH_SIZEinteger20Number of conversations processed per batch per pod
CONVERSATION_ANALYSIS_MAX_RETRIESinteger3Max retry attempts for failed conversation analyses before marking as permanently failed
CONVERSATION_ANALYSIS_LLM_MODELstring"gemini-3-flash"LLM model used for conversation analysis; should be a fast, cost-efficient model

Stale Datasource Detection​

Nightly background job that identifies datasources with no recent usage or updates and marks them as stale to prompt review or cleanup.

ParameterTypeDefaultDescription
STALE_DATASOURCE_ENABLEDbooleanfalseEnable the nightly stale datasource detection job
STALE_DATASOURCE_SCHEDULEstring"0 3 * * *"Cron schedule (UTC) for the detection job; defaults to 3 AM daily
STALE_DATASOURCE_NO_USAGE_DAYSinteger90Days without usage metrics after which a datasource is considered stale
STALE_DATASOURCE_NO_UPDATE_DAYSinteger120Days without any update used as a fallback staleness criterion when no usage metrics are available
STALE_DATASOURCE_GRACE_DAYSinteger7Newly created datasources are never marked stale within this grace period
STALE_DATASOURCE_BATCH_SIZEinteger100Elasticsearch query batch size for metrics aggregation during detection

Analytics​

ParameterTypeDefaultDescription
ANALYTICS_DEFAULT_PAGE_SIZEinteger20Default number of rows returned per page by analytics API endpoints

Environment-Specific Configuration​

Loading Configuration​

CodeMie uses Pydantic Settings to load configuration from multiple sources with precedence:

  1. Environment variables - Highest priority, overrides all other sources
  2. .env file - Loaded from project root, convenient for local development
  3. Default values - Specified in configuration classes as fallbacks

Sensitive Information​

The following parameter patterns are automatically masked in logs and exports:

  • Any parameter ending with: KEY, PASSWORD, SECRET, TOKEN
  • Explicitly masked: AZURE_STORAGE_CONNECTION_STRING, PG_URL, ELASTIC_URL

Security Best Practice: Use secret management services in production rather than plain environment variables.

Environment Detection​

The application detects deployment environment using the ENV parameter:

config.is_local  # Returns True when ENV == "local"

This affects logging format (JSON vs human-readable) and security defaults.

LLM Model Configuration​

LLM models are configured via YAML files located at LLM_TEMPLATES_ROOT/llm-{MODELS_ENV}-config.yaml.

Model Configuration Structure​

Each model entry supports these configuration options:

FieldTypeDescription
base_namestringCanonical model identifier (e.g., gpt-4, claude-3-opus-20240229)
deployment_namestringProvider-specific deployment name (Azure deployment, Bedrock model ID)
labelstringHuman-friendly display name shown in UI model selector
multimodalbooleanModel supports vision (images/video) in addition to text
react_agentbooleanCompatible with ReAct agent pattern (reasoning + acting)
enabledbooleanModel available for selection (allows disabling without removal)
providerstringProvider type: azure_openai, aws_bedrock, google_vertexai, anthropic
default_for_categorieslistCategories where this model is auto-selected
cost.inputfloatUSD per input token for cost tracking
cost.outputfloatUSD per output token
cost.cache_read_input_token_costfloatUSD per cached token (for providers supporting caching)
max_output_tokensintegerMaximum generation length supported by model
features.streamingbooleanSupports streaming responses for real-time output
features.toolsbooleanSupports function calling / tool use
features.parallel_tool_callsbooleanWhether the model can execute multiple tool calls in a single inference round. Defaults to false. Set to false explicitly for reasoning models (o-series) that do not support the parallel_tool_calls OpenAI parameter — sending it to these models causes an API error. When false, the platform strips the parameter from every outgoing request to that model.
How parallel tool calls work

When parallel_tool_calls is true for a model, the agent can issue and stream multiple tool calls simultaneously within one inference round. Results arrive concurrently and are rendered in the UI as parallel entries under the same thought step.

Standard GPT and Claude models support parallel tool calls. Reasoning models (o1, o3, o3-mini, o4-mini, and similar) do not — always set parallel_tool_calls: false in their features block.

Model Categories​

Models can be designated as defaults for specific use cases:

  • global - Fallback default for all operations
  • chat - Conversational interactions and general Q&A
  • code - Code generation, review, and analysis
  • documentation - Technical documentation generation
  • summarization - Long-form text summarization
  • translation - Language translation tasks
  • knowledge_base - Information retrieval and RAG
  • workflow - Workflow step execution
  • file_analysis - Document and file content analysis
  • reasoning - Complex reasoning and problem-solving
  • planning - Strategic planning and task decomposition

Customer Configuration​

Customer-specific settings are loaded from CUSTOMER_CONFIG_DIR/customer-config.yaml. See CodeMie Customer Feature Configuration for the full reference.

Authorized Applications Configuration​

External applications that can access CodeMie APIs via JWT authentication are configured in AUTHORIZED_APPS_CONFIG_DIR/authorized-applications-config.yaml.

Application Configuration Structure​

authorized_applications:
  - name: app-name # Application identifier
    public_key_url: https://app.trusted.example/.well-known/public-key # JWT verification key URL, must use https and match an allowed domain
    # OR
    public_key_path: /path/to/public/key.pem # Local public key file
    allowed_resources: # Permitted resource types
      - ASSISTANT
      - WORKFLOW
      - CONVERSATION

Resource Types​

Control granular access to CodeMie resources:

  • ASSISTANT - Create, read, update assistant configurations
  • WORKFLOW - Execute workflows and access results
  • CONVERSATION - Read/write conversation history
  • USER - User profile management
  • PROJECT - Project-level access

Public Key URL Domain Allowlist​

public_key_url values are validated against a domain allowlist before the key is fetched — once when the configuration loads (fails fast on startup) and again immediately before each fetch (defense in depth). This stops a tampered or misconfigured entry from pointing at an attacker-controlled host.

ParameterTypeDefaultDescription
AUTHORIZED_APPS_ALLOWED_KEY_DOMAINSlist[string][]Domains permitted to host public_key_url keys. A host matches if it equals a listed domain or is a subdomain of one.

Validation rules:

  • public_key_url must use https.
  • The URL host must not be an IP literal.
  • The URL host must equal, or be a subdomain of, one of the configured domains.
  • An empty allowlist (the default) rejects every URL-based key — only public_key_path (local file) entries are permitted until at least one domain is configured.

Override with a JSON array via environment variable:

AUTHORIZED_APPS_ALLOWED_KEY_DOMAINS=["trusted.example","keys.trusted.example"]

See Also​