> ## Documentation Index > Fetch the complete documentation index at: https://docs.mypraxos.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuration Guide > Configure Praxos for your environment ## Overview Praxos is configured primarily through environment variables. This guide covers all available configuration options. ## Core Configuration ### Environment ```bash theme={null} ENVIRONMENT=production # development, staging, production LOG_LEVEL=info # debug, info, warning, error, critical ``` ### Server ```bash theme={null} HOST=0.0.0.0 # Listen address PORT=8000 # Server port RELOAD=false # Auto-reload on code changes (dev only) WORKERS=4 # Number of worker processes ``` ## Database Configuration ### MongoDB ```bash theme={null} MONGODB_URI=mongodb://username:password@host:27017/ DATABASE_NAME=hetairos MONGODB_MAX_POOL_SIZE=100 MONGODB_MIN_POOL_SIZE=10 MONGODB_SERVER_SELECTION_TIMEOUT_MS=5000 ``` ### Azure Cosmos DB ```bash theme={null} AZURE_COSMOS_ENDPOINT=https://your-account.documents.azure.com:443/ AZURE_COSMOS_KEY=your-cosmos-key DATABASE_NAME=hetairos ``` ## Message Queue ### Azure Service Bus ```bash theme={null} AZURE_SERVICE_BUS_CONNECTION_STRING=Endpoint=sb://... AZURE_SERVICE_BUS_QUEUE_NAME=agent_tasks AZURE_SERVICE_BUS_MAX_CONCURRENT_MESSAGES=10 ``` ### Redis (Alternative) ```bash theme={null} REDIS_URL=redis://localhost:6379 REDIS_MAX_CONNECTIONS=50 REDIS_SOCKET_KEEPALIVE=true ``` ## LLM Configuration ### Portkey (Gateway) ```bash theme={null} PORTKEY_API_KEY=your-portkey-key PORTKEY_VIRTUAL_KEY=your-virtual-key ``` ### OpenAI ```bash theme={null} OPENAI_API_KEY=your-openai-key OPENAI_MODEL=gpt-4-turbo-preview OPENAI_MAX_TOKENS=4096 OPENAI_TEMPERATURE=0.7 ``` ### Google Gemini ```bash theme={null} GOOGLE_API_KEY=your-google-key GOOGLE_MODEL=gemini-pro GOOGLE_MAX_TOKENS=8192 ``` ## Secrets Management ### Azure Key Vault ```bash theme={null} AZURE_KEY_VAULT_URL=https://your-keyvault.vault.azure.net/ AZURE_TENANT_ID=your-tenant-id AZURE_CLIENT_ID=your-client-id AZURE_CLIENT_SECRET=your-client-secret ``` When using Key Vault, individual secrets can be: * Stored in Key Vault and auto-loaded at runtime * Or specified directly as env vars ## Integration Configuration ### Telegram ```bash theme={null} TELEGRAM_BOT_TOKEN=123456:ABC-DEF... TELEGRAM_WEBHOOK_URL=https://your-domain.com/telegram/webhook TELEGRAM_MAX_MESSAGE_LENGTH=4096 TELEGRAM_PARSE_MODE=Markdown # or HTML ``` ### Discord ```bash theme={null} DISCORD_BOT_TOKEN=your-discord-token DISCORD_APPLICATION_ID=your-app-id DISCORD_COMMAND_PREFIX=! DISCORD_MAX_MESSAGE_LENGTH=2000 ``` ### Slack ```bash theme={null} SLACK_BOT_TOKEN=xoxb-... SLACK_SIGNING_SECRET=your-signing-secret SLACK_APP_TOKEN=xapp-... # For Socket Mode SLACK_SOCKET_MODE=false ``` ### WhatsApp ```bash theme={null} WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id WHATSAPP_ACCESS_TOKEN=your-access-token WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-verify-token ``` ### Google Services ```bash theme={null} GOOGLE_CLIENT_ID=your-client-id GOOGLE_CLIENT_SECRET=your-client-secret GOOGLE_REDIRECT_URI=https://your-domain.com/auth/google/callback GOOGLE_API_KEY=your-api-key # For services without OAuth ``` ### Microsoft 365 ```bash theme={null} MICROSOFT_CLIENT_ID=your-app-id MICROSOFT_CLIENT_SECRET=your-secret MICROSOFT_TENANT_ID=your-tenant-id MICROSOFT_REDIRECT_URI=https://your-domain.com/auth/microsoft/callback ``` ### Notion ```bash theme={null} NOTION_CLIENT_ID=your-client-id NOTION_CLIENT_SECRET=your-client-secret NOTION_REDIRECT_URI=https://your-domain.com/auth/notion/callback ``` ### Trello ```bash theme={null} TRELLO_API_KEY=your-api-key TRELLO_TOKEN=your-token ``` ### Dropbox ```bash theme={null} DROPBOX_APP_KEY=your-app-key DROPBOX_APP_SECRET=your-app-secret DROPBOX_REDIRECT_URI=https://your-domain.com/auth/dropbox/callback ``` ## Feature Flags ```bash theme={null} # Enable/disable features ENABLE_BROWSER_TOOL=true ENABLE_SCHEDULED_TASKS=true ENABLE_FILE_PROCESSING=true ENABLE_VOICE_MESSAGES=true ENABLE_VISION_FEATURES=false # Future # Feature limits MAX_FILE_SIZE_MB=25 MAX_MESSAGE_HISTORY=100 MAX_CONCURRENT_TASKS_PER_USER=5 ``` ## Performance Tuning ### Worker Configuration ```bash theme={null} MAX_WORKERS=4 # Number of worker processes WORKER_TIMEOUT_SECONDS=300 # Worker timeout MAX_TASKS_PER_WORKER=100 # Tasks before worker restart WORKER_PREFETCH_COUNT=5 # Messages to prefetch ``` ### Caching ```bash theme={null} ENABLE_CACHE=true CACHE_TTL_SECONDS=300 # 5 minutes CACHE_MAX_SIZE_MB=100 USER_CONTEXT_CACHE_TTL=300 INTEGRATION_CACHE_TTL=3600 ``` ### Rate Limiting ```bash theme={null} RATE_LIMIT_ENABLED=true RATE_LIMIT_PER_USER=100 # Requests per minute RATE_LIMIT_BURST=20 # Burst allowance ``` ### Timeouts ```bash theme={null} HTTP_CLIENT_TIMEOUT=30 # HTTP request timeout (seconds) DATABASE_QUERY_TIMEOUT=10 # Database query timeout TOOL_EXECUTION_TIMEOUT=120 # Tool execution timeout BROWSER_TIMEOUT=60 # Browser automation timeout ``` ## Logging Configuration ### Log Levels ```bash theme={null} LOG_LEVEL=info # Global log level LOG_FORMAT=json # json or text # Per-module log levels LOG_LEVEL_LANGCHAIN=warning LOG_LEVEL_HTTPX=warning LOG_LEVEL_AZURE=warning LOG_LEVEL_PLAYWRIGHT=error ``` ### Log Destinations ```bash theme={null} LOG_TO_FILE=true LOG_FILE_PATH=/var/log/hetairos/app.log LOG_FILE_MAX_BYTES=10485760 # 10MB LOG_FILE_BACKUP_COUNT=5 LOG_TO_CONSOLE=true LOG_TO_AZURE_INSIGHTS=true # If using Azure ``` ## Security Configuration ### CORS ```bash theme={null} CORS_ENABLED=true CORS_ORIGINS=["https://yourdomain.com"] CORS_ALLOW_CREDENTIALS=true ``` ### API Security ```bash theme={null} API_KEY_REQUIRED=true # Require API key for endpoints API_KEYS=["key1", "key2"] # Allowed API keys ENABLE_RATE_LIMITING=true ``` ### Data Protection ```bash theme={null} ENCRYPT_USER_DATA=true ENCRYPTION_KEY=your-encryption-key MASK_SENSITIVE_LOGS=true ``` ## Monitoring ### Metrics ```bash theme={null} ENABLE_METRICS=true METRICS_PORT=9090 PROMETHEUS_MULTIPROC_DIR=/tmp/prometheus ``` ### Health Checks ```bash theme={null} HEALTH_CHECK_ENABLED=true HEALTH_CHECK_PATH=/health READINESS_CHECK_PATH=/ready ``` ### Azure Application Insights ```bash theme={null} APPINSIGHTS_INSTRUMENTATION_KEY=your-key APPINSIGHTS_CONNECTION_STRING=InstrumentationKey=... ENABLE_TELEMETRY=true ``` ## Scheduled Tasks ```bash theme={null} ENABLE_SCHEDULED_TASKS=true SCHEDULED_TASK_CHECK_INTERVAL=60 # seconds MAX_SCHEDULED_TASKS_PER_USER=50 ``` ## Browser Configuration ```bash theme={null} # Playwright settings PLAYWRIGHT_BROWSER=chromium # chromium, firefox, webkit PLAYWRIGHT_HEADLESS=true PLAYWRIGHT_TIMEOUT=60000 # milliseconds BROWSER_MAX_STEPS=10 # Max AI browser actions ``` ## Webhook Configuration ```bash theme={null} WEBHOOK_BASE_URL=https://your-domain.com WEBHOOK_SECRET=your-webhook-secret WEBHOOK_TIMEOUT=5 # seconds ``` ## Time Zone ```bash theme={null} TIMEZONE=UTC # Default timezone TIMEZONE_DATABASE_PATH=/usr/share/zoneinfo ``` ## Example Configurations ### Development ```bash theme={null} ENVIRONMENT=development LOG_LEVEL=debug RELOAD=true MONGODB_URI=mongodb://localhost:27017/ DATABASE_NAME=hetairos_dev REDIS_URL=redis://localhost:6379 ENABLE_CACHE=false ``` ### Staging ```bash theme={null} ENVIRONMENT=staging LOG_LEVEL=info RELOAD=false MONGODB_URI=mongodb+srv://... DATABASE_NAME=hetairos_staging AZURE_SERVICE_BUS_CONNECTION_STRING=... ENABLE_CACHE=true ENABLE_METRICS=true ``` ### Production ```bash theme={null} ENVIRONMENT=production LOG_LEVEL=info RELOAD=false WORKERS=8 # Use Azure Cosmos DB AZURE_COSMOS_ENDPOINT=https://... DATABASE_NAME=hetairos # Use Azure Service Bus AZURE_SERVICE_BUS_CONNECTION_STRING=... # Use Azure Key Vault AZURE_KEY_VAULT_URL=https://... # Monitoring ENABLE_METRICS=true APPINSIGHTS_CONNECTION_STRING=... # Security API_KEY_REQUIRED=true ENCRYPT_USER_DATA=true MASK_SENSITIVE_LOGS=true # Performance ENABLE_CACHE=true CACHE_TTL_SECONDS=600 MAX_WORKERS=8 WORKER_PREFETCH_COUNT=10 ``` ## Configuration File (.env) Create a `.env` file: ```bash theme={null} # Core ENVIRONMENT=production LOG_LEVEL=info # Database MONGODB_URI=your-mongodb-uri DATABASE_NAME=hetairos # Queue AZURE_SERVICE_BUS_CONNECTION_STRING=your-connection-string # Secrets AZURE_KEY_VAULT_URL=your-keyvault-url # LLM PORTKEY_API_KEY=your-portkey-key OPENAI_API_KEY=your-openai-key # Integrations (configure as needed) TELEGRAM_BOT_TOKEN=your-telegram-token DISCORD_BOT_TOKEN=your-discord-token # ... more integrations ``` ## Loading Configuration ### From Environment ```python theme={null} import os from dotenv import load_dotenv load_dotenv() environment = os.getenv("ENVIRONMENT", "development") log_level = os.getenv("LOG_LEVEL", "info") ``` ### From Azure Key Vault ```python theme={null} from azure.identity import DefaultAzureCredential from azure.keyvault.secrets import SecretClient credential = DefaultAzureCredential() client = SecretClient( vault_url=os.getenv("AZURE_KEY_VAULT_URL"), credential=credential ) telegram_token = client.get_secret("telegram-bot-token").value ``` ## Validation Praxos validates configuration on startup: ```python theme={null} # Example validation required_vars = [ "MONGODB_URI", "PORTKEY_API_KEY", "OPENAI_API_KEY" ] for var in required_vars: if not os.getenv(var): raise ValueError(f"Required environment variable {var} not set") ``` ## Troubleshooting ### Configuration Not Loading * Check `.env` file exists * Verify file is in correct directory * Check for typos in variable names * Ensure proper file permissions ### Secrets Not Found * Verify Azure Key Vault URL is correct * Check authentication credentials * Ensure secrets exist in Key Vault * Verify secret names match ### Connection Errors * Validate connection strings * Check network connectivity * Verify firewall rules * Test credentials ## Best Practices 1. **Never commit secrets** - Use `.gitignore` for `.env` files 2. **Use Key Vault in production** - Don't store secrets in env vars 3. **Separate configs per environment** - dev, staging, production 4. **Validate on startup** - Fail fast if config is incorrect 5. **Document all variables** - Maintain configuration documentation 6. **Use defaults wisely** - Provide sensible defaults 7. **Environment-specific overrides** - Allow per-environment customization ## Next Steps Deploy to Kubernetes Review requirements Local development setup