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.
Overview
Praxos is configured primarily through environment variables. This guide covers all available configuration options.
Core Configuration
Environment
ENVIRONMENT=production # development, staging, production
LOG_LEVEL=info # debug, info, warning, error, critical
Server
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
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
AZURE_COSMOS_ENDPOINT=https://your-account.documents.azure.com:443/
AZURE_COSMOS_KEY=your-cosmos-key
DATABASE_NAME=hetairos
Message Queue
Azure Service Bus
AZURE_SERVICE_BUS_CONNECTION_STRING=Endpoint=sb://...
AZURE_SERVICE_BUS_QUEUE_NAME=agent_tasks
AZURE_SERVICE_BUS_MAX_CONCURRENT_MESSAGES=10
Redis (Alternative)
REDIS_URL=redis://localhost:6379
REDIS_MAX_CONNECTIONS=50
REDIS_SOCKET_KEEPALIVE=true
LLM Configuration
Portkey (Gateway)
PORTKEY_API_KEY=your-portkey-key
PORTKEY_VIRTUAL_KEY=your-virtual-key
OpenAI
OPENAI_API_KEY=your-openai-key
OPENAI_MODEL=gpt-4-turbo-preview
OPENAI_MAX_TOKENS=4096
OPENAI_TEMPERATURE=0.7
Google Gemini
GOOGLE_API_KEY=your-google-key
GOOGLE_MODEL=gemini-pro
GOOGLE_MAX_TOKENS=8192
Secrets Management
Azure Key Vault
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
- Stored in Key Vault and auto-loaded at runtime
- Or specified directly as env vars
Integration Configuration
Telegram
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
DISCORD_BOT_TOKEN=your-discord-token
DISCORD_APPLICATION_ID=your-app-id
DISCORD_COMMAND_PREFIX=!
DISCORD_MAX_MESSAGE_LENGTH=2000
Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_APP_TOKEN=xapp-... # For Socket Mode
SLACK_SOCKET_MODE=false
WhatsApp
WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
WHATSAPP_ACCESS_TOKEN=your-access-token
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-verify-token
Google Services
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
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
NOTION_CLIENT_ID=your-client-id
NOTION_CLIENT_SECRET=your-client-secret
NOTION_REDIRECT_URI=https://your-domain.com/auth/notion/callback
Trello
TRELLO_API_KEY=your-api-key
TRELLO_TOKEN=your-token
Dropbox
DROPBOX_APP_KEY=your-app-key
DROPBOX_APP_SECRET=your-app-secret
DROPBOX_REDIRECT_URI=https://your-domain.com/auth/dropbox/callback
Feature Flags
# 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
Worker Configuration
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
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
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_USER=100 # Requests per minute
RATE_LIMIT_BURST=20 # Burst allowance
Timeouts
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
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
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
CORS_ENABLED=true
CORS_ORIGINS=["https://yourdomain.com"]
CORS_ALLOW_CREDENTIALS=true
API Security
API_KEY_REQUIRED=true # Require API key for endpoints
API_KEYS=["key1", "key2"] # Allowed API keys
ENABLE_RATE_LIMITING=true
Data Protection
ENCRYPT_USER_DATA=true
ENCRYPTION_KEY=your-encryption-key
MASK_SENSITIVE_LOGS=true
Monitoring
Metrics
ENABLE_METRICS=true
METRICS_PORT=9090
PROMETHEUS_MULTIPROC_DIR=/tmp/prometheus
Health Checks
HEALTH_CHECK_ENABLED=true
HEALTH_CHECK_PATH=/health
READINESS_CHECK_PATH=/ready
Azure Application Insights
APPINSIGHTS_INSTRUMENTATION_KEY=your-key
APPINSIGHTS_CONNECTION_STRING=InstrumentationKey=...
ENABLE_TELEMETRY=true
Scheduled Tasks
ENABLE_SCHEDULED_TASKS=true
SCHEDULED_TASK_CHECK_INTERVAL=60 # seconds
MAX_SCHEDULED_TASKS_PER_USER=50
Browser Configuration
# 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
WEBHOOK_BASE_URL=https://your-domain.com
WEBHOOK_SECRET=your-webhook-secret
WEBHOOK_TIMEOUT=5 # seconds
Time Zone
TIMEZONE=UTC # Default timezone
TIMEZONE_DATABASE_PATH=/usr/share/zoneinfo
Example Configurations
Development
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
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
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:
# 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
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
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:
# 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
- Never commit secrets - Use
.gitignore for .env files
- Use Key Vault in production - Don’t store secrets in env vars
- Separate configs per environment - dev, staging, production
- Validate on startup - Fail fast if config is incorrect
- Document all variables - Maintain configuration documentation
- Use defaults wisely - Provide sensible defaults
- Environment-specific overrides - Allow per-environment customization
Next Steps
Kubernetes Deployment
Deploy to Kubernetes
Requirements
Review requirements
Quickstart
Local development setup
