Configuration Files Kortix uses environment files for configuration:
backend/.env - Backend API configurationapps/frontend/.env.local - Frontend configuration.setup_progress - Setup wizard state (can be deleted after setup)
Never commit .env files to version control. They contain sensitive API keys and secrets.
Required Configuration These settings are required for Kortix to function:
Supabase # Supabase project configuration SUPABASE_URL = https://your-project.supabase.co SUPABASE_ANON_KEY = your-anon-key SUPABASE_SERVICE_ROLE_KEY = your-service-role-key SUPABASE_JWT_SECRET = your-jwt-secret SUPABASE_PROJECT_REF = your-project-ref # Database connection DATABASE_URL = postgresql://postgres.your-project:[email protected] :6543/postgres
Finding Supabase credentials:
Go to Supabase Dashboard
Select your project
Go to Project Settings → API:
Project URL - Shown at the topAnon key - Under “Project API keys”Service role key - Under “Project API keys” (keep secret!)JWT Secret - Under “JWT Settings” (copy exactly!)
Go to Project Settings → Database:
Connection string - Use “Transaction mode” pooler
The JWT secret must match exactly or authentication will fail with “alg value is not allowed” errors.
Daytona # Daytona sandbox configuration DAYTONA_API_KEY = your-api-key DAYTONA_SERVER_URL = https://app.daytona.io/api DAYTONA_TARGET = us
Get your API key from app.daytona.io/keys
Composio # Composio tool integrations COMPOSIO_API_KEY = your-api-key COMPOSIO_WEBHOOK_SECRET = your-webhook-secret
Get your API key from app.composio.dev/settings/api-keys
LLM Provider Kortix requires at least one LLM provider. Configure your main provider:
# Main LLM selection (anthropic, bedrock, grok, openai, minimax) MAIN_LLM = anthropic # Optional: Override default model MAIN_LLM_MODEL = anthropic/claude-haiku-4-5-20251001 # Required based on MAIN_LLM selection: # For Anthropic ANTHROPIC_API_KEY = sk-ant-... # For AWS Bedrock AWS_BEARER_TOKEN_BEDROCK = your-bearer-token # For Grok, OpenAI, MiniMax (via OpenRouter) OPENROUTER_API_KEY = your-api-key # For background tasks (required) OPENAI_API_KEY = sk-...
Default models per provider:
anthropic - claude-haiku-4-5-20251001bedrock - bedrock/anthropic.claude-3-haiku-20240307-v1:0grok - openrouter/x-ai/grok-4.1-fastopenai - openrouter/openai/gpt-4o-miniminimax - openrouter/minimax/minimax-m2.1 You can override these with MAIN_LLM_MODEL. Optional Configuration Additional LLM Providers Configure multiple LLM providers for flexibility:
# Additional LLM providers (all optional) OPENAI_API_KEY = sk-... ANTHROPIC_API_KEY = sk-ant-... GROQ_API_KEY = gsk_... OPENROUTER_API_KEY = sk-or-... XAI_API_KEY = xai-... GEMINI_API_KEY = AIza... MORPH_API_KEY = morph-... # OpenAI-compatible endpoints OPENAI_COMPATIBLE_API_KEY = your-key OPENAI_COMPATIBLE_API_BASE = https://api.example.com/v1
Search & Web APIs # Search APIs (all optional) TAVILY_API_KEY = tvly-... FIRECRAWL_API_KEY = fc-... FIRECRAWL_URL = https://api.firecrawl.dev SERPER_API_KEY = ... EXA_API_KEY = ... SEMANTIC_SCHOLAR_API_KEY = ...
Provider details: RapidAPI # RapidAPI for additional integrations RAPID_API_KEY = your-rapid-api-key
Get your key from rapidapi.com/developer/security
Webhooks # Webhook configuration WEBHOOK_BASE_URL = https://your-domain.com TRIGGER_WEBHOOK_SECRET = your-secret SUPABASE_WEBHOOK_SECRET = your-supabase-webhook-secret
MCP (Model Context Protocol) # MCP credential encryption MCP_CREDENTIAL_ENCRYPTION_KEY = your-encryption-key
Frontend Configuration The frontend .env.local file:
# Supabase (same as backend) NEXT_PUBLIC_SUPABASE_URL = https://your-project.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY = your-anon-key # Backend URL NEXT_PUBLIC_BACKEND_URL = http://localhost:8000/v1 # Frontend URL NEXT_PUBLIC_URL = http://localhost:3000 # Environment mode (local, staging, production) NEXT_PUBLIC_ENV_MODE = local # Optional: Analytics and monitoring NEXT_PUBLIC_POSTHOG_KEY = phc_... NEXT_PUBLIC_SENTRY_DSN = https://...
Redis Configuration Redis settings (used for caching and queues):
# Redis connection (Docker Compose default) REDIS_HOST = redis REDIS_PORT = 6379 REDIS_PASSWORD = REDIS_SSL = False # For external Redis (production) REDIS_HOST = your-redis-host.com REDIS_PORT = 6379 REDIS_PASSWORD = your-password REDIS_SSL = True
Backend Service Configuration # Environment mode ENV_MODE = production # or development, local # Worker configuration (for Docker/production) WORKERS = 4 # Gunicorn workers (2 per CPU recommended) TIMEOUT = 75 # Worker timeout in seconds # Python path PYTHONPATH = /app
Security Configuration Encryption Keys # Auto-generated encryption key for sensitive data ENCRYPTION_KEY = your-auto-generated-key # Kortix admin API key (for admin operations) KORTIX_ADMIN_API_KEY = your-admin-key
These are auto-generated during setup. Never share or commit them.
JWT Configuration JWT settings are inherited from Supabase:
SUPABASE_JWT_SECRET = your-jwt-secret
This must match your Supabase project’s JWT secret exactly.
Monitoring & Observability # Sentry error tracking SENTRY_DSN = https://[email protected] /... # Freestyle API monitoring FREESTYLE_API_KEY = your-freestyle-key # Cloudflare CLOUDFLARE_API_TOKEN = your-cloudflare-token
Production Deployment Variables For production deployments (AWS, etc.):
# Frontend URLs (production) NEXT_PUBLIC_BACKEND_URL = https://api.yourdomain.com/v1 NEXT_PUBLIC_URL = https://yourdomain.com NEXT_PUBLIC_ENV_MODE = production # Backend configuration ENV_MODE = production WORKERS = 8 # Scale based on CPU cores TIMEOUT = 120 # Redis (managed service) REDIS_HOST = your-redis.cache.amazonaws.com REDIS_PORT = 6379 REDIS_PASSWORD = your-password REDIS_SSL = True
Environment Variable Reference Quick Lookup Table Category Variable Required Default Supabase SUPABASE_URLYes - SUPABASE_ANON_KEYYes - SUPABASE_SERVICE_ROLE_KEYYes - SUPABASE_JWT_SECRETYes - DATABASE_URLYes - Daytona DAYTONA_API_KEYYes - DAYTONA_SERVER_URLNo https://app.daytona.io/api DAYTONA_TARGETNo us Composio COMPOSIO_API_KEYYes - LLM MAIN_LLMYes anthropic MAIN_LLM_MODELNo (provider default) OPENAI_API_KEYYes* - ANTHROPIC_API_KEYYes* - Redis REDIS_HOSTNo redis REDIS_PORTNo 6379 Backend ENV_MODENo production WORKERSNo 4 TIMEOUTNo 75
*Required based on MAIN_LLM selection
Configuration Best Practices
Use Strong Secrets
Generate strong, unique values for all secrets and encryption keys.
Keep Credentials Separate
Never commit .env files. Use .gitignore and secret management tools.
Use Environment-Specific Configs
Maintain separate configurations for development, staging, and production.
Rotate Keys Regularly
Periodically rotate API keys and secrets, especially after team changes.
Monitor Usage
Track API usage and costs for LLM providers and third-party services.
Updating Configuration To update configuration after initial setup:
# Use the setup wizard python setup.py # Or manually edit files nano backend/.env nano apps/frontend/.env.local # Restart services to apply changes python start.py restart
Next Steps
Deployment Deploy Kortix to production
Troubleshooting Fix common configuration issues