Configuration

Complete guide to all Kortix configuration options

Configuration Files

Kortix uses environment files for configuration:

• backend/.env - Backend API configuration
• apps/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:[e-mail]:6543/postgres

Finding Supabase credentials:

1. Go to Supabase Dashboard
2. Select your project
3. Go to Project Settings → API:
   • Project URL - Shown at the top
   • Anon key - Under “Project API keys”
   • Service role key - Under “Project API keys” (keep secret!)
   • JWT Secret - Under “JWT Settings” (copy exactly!)
4. 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-20251001
• bedrock - bedrock/anthropic.claude-3-haiku-20240307-v1:0
• grok - openrouter/x-ai/grok-4.1-fast
• openai - openrouter/openai/gpt-4o-mini
• minimax - 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:

• Tavily - AI-powered search API (tavily.com)
• Firecrawl - Web scraping and crawling (firecrawl.dev)
• Serper - Google search API (serper.dev)
• Exa - Semantic search API (exa.ai)
• Semantic Scholar - Academic paper search (semanticscholar.org)

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://[e-mail]/...

# 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_URL	Yes	-
	SUPABASE_ANON_KEY	Yes	-
	SUPABASE_SERVICE_ROLE_KEY	Yes	-
	SUPABASE_JWT_SECRET	Yes	-
	DATABASE_URL	Yes	-
Daytona
	DAYTONA_API_KEY	Yes	-
	DAYTONA_SERVER_URL	No	https://app.daytona.io/api
	DAYTONA_TARGET	No	us
Composio
	COMPOSIO_API_KEY	Yes	-
LLM
	MAIN_LLM	Yes	anthropic
	MAIN_LLM_MODEL	No	(provider default)
	OPENAI_API_KEY	Yes*	-
	ANTHROPIC_API_KEY	Yes*	-
Redis
	REDIS_HOST	No	redis
	REDIS_PORT	No	6379
Backend
	ENV_MODE	No	production
	WORKERS	No	4
	TIMEOUT	No	75

*Required based on MAIN_LLM selection

Configuration Best Practices

1. Use Strong Secrets

   Generate strong, unique values for all secrets and encryption keys.

2. Keep Credentials Separate

   Never commit .env files. Use .gitignore and secret management tools.

3. Use Environment-Specific Configs

   Maintain separate configurations for development, staging, and production.

4. Rotate Keys Regularly

   Periodically rotate API keys and secrets, especially after team changes.

5. 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