Deployment options

KaireonAI is a proprietary, commercially licensed platform. There are three ways to run it:

Cloud

Hosted SaaS — the default. We run KaireonAI for you on shared infrastructure. Sign up, pick a plan by decision volume, and go live — no servers to maintain. See Licensing & Plans.

Dedicated

Private cloud, single-tenant. An isolated instance we operate for you, with dedicated compute, storage, and networking. For teams with data-isolation or compliance requirements. Contact sales.

Enterprise on-prem

You run it, under a commercial license. Deploy inside your own VPC or air-gapped cluster. Available on the Enterprise plan only — not free, not open, not self-serve. Contact sales.

The operational guides in this section (Docker Compose, Kubernetes / Helm, cloud infrastructure) apply to Enterprise on-prem deployments and internal development. Image and source access is provisioned as part of an Enterprise agreement. Most customers run on the fully hosted Cloud plan and never touch these.

Enterprise on-prem topologies

Enterprise licensees can run KaireonAI in whichever topology fits their infrastructure:

Local / evaluation

Run on a workstation with PostgreSQL and optional Redis. For licensed development and evaluation.

Managed cloud (App Runner)

Deploy to AWS App Runner with Supabase (PostgreSQL) and Upstash (Redis).

Kubernetes (Helm)

Deploy to any Kubernetes cluster using the provided Helm chart.

Comparison of on-prem topologies

	Local	Cloud (App Runner)	Kubernetes (Helm)
Best for	Development, evaluation	Small-to-medium production	Enterprise production
Database	Local PostgreSQL	Supabase	Self-managed / RDS
Cache	Local Redis (optional)	Upstash	Self-managed Redis
Scaling	Single instance	Auto-scaling (App Runner)	HPA + custom policies
Monitoring	Dev tools	CloudWatch	Prometheus + Grafana
TLS	Not required	Auto (App Runner)	Ingress controller
Setup time	5 minutes	30 minutes	1–2 hours

Docker Images

KaireonAI builds two Docker images:

Image	Purpose
`kaireon-api`	Main Next.js application (UI + API routes)
`kaireon-worker`	Background job processing (pipelines, model retraining)

The API Dockerfile lives in the platform/ directory, so build from there. You push images to Amazon ECR and tag them with the git SHA plus latest:

cd platform
docker build -t kaireon-api .
docker tag kaireon-api:latest <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/kaireon-api:$(git rev-parse --short HEAD)
docker push <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/kaireon-api:$(git rev-parse --short HEAD)

Environment Variables

All deployment methods use the same core environment variables. The platform validates these at startup and will fail fast if required values are missing in production.

Core (Required)

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string (`postgresql://...`)
`NEXTAUTH_SECRET`	Yes (prod)	Random secret for signing JWT sessions (min 32 chars in production)
`NEXTAUTH_URL`	Yes (prod)	Public URL of the application (e.g., `https://your-domain.com`)

Security (Required in Production)

Variable	Required	Description
`JWT_SIGNING_SECRET`	Yes (prod)	Secret for signing API and OAuth tokens
`CONNECTOR_ENCRYPTION_KEY`	Yes (prod)	AES-256 key for encrypting connector credentials at rest
`CONNECTOR_ENCRYPTION_KEY_VERSION`	No	Current key version (default: `1`)
`CONNECTOR_ENCRYPTION_KEY_PREVIOUS`	No	Previous key for rotation
`WEBHOOK_SIGNING_SECRET`	Yes (prod)	HMAC secret for signing outbound webhooks
`API_KEY_PEPPER`	Yes (prod)	HMAC pepper for hashing API keys

Authentication

Variable	Required	Description
`GOOGLE_CLIENT_ID`	No	Google OAuth client ID (for SSO)
`GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret
`SES_FROM_EMAIL`	No	Sender address for transactional emails (default: `support@kaireonai.com`)
`AWS_REGION`	No	AWS region for SES (default: `us-east-1`)

Infrastructure

Variable	Required	Description
`REDIS_URL`	No	Redis connection string for enrichment cache, rate limiting, circuit breakers, and event publishing
`ML_WORKER_URL`	No	URL of the ML Worker for AI features (e.g., `http://localhost:8000`)
`PG_POOL_MAX`	No	Max PostgreSQL pool connections (default: `50`)
PORT	No	HTTP port the platform process binds to (default: `3000`)

Observability

Variable	Required	Description
`LOG_LEVEL`	No	Logging level: `debug`, `info`, `warn`, `error` (default: `info`)
`OTEL_EXPORTER_OTLP_ENDPOINT`	No	OpenTelemetry endpoint URL (enables distributed tracing when set)
`SLOW_API_THRESHOLD_MS`	No	Log slow API calls exceeding this threshold (default: `150`)

Security Headers

Variable	Required	Description
`CORS_ALLOWED_ORIGINS`	Yes (prod)	Comma-separated allowed origins (must not be `*` in production)
`CSP_POLICY`	No	Custom Content Security Policy header
`CSP_DISABLED`	No	Set `true` to disable CSP (not recommended in production)

Decisioning Tuning

Variable	Required	Description
`RETRAIN_EVERY_N`	No	Auto-retrain models every N outcomes (default: `100`)
`ATTRIBUTION_TIMEOUT_MS`	No	Timeout for attribution lookups (default: `5000`)
`RATE_LIMIT_TIER`	No	Rate limiting tier override

The following decisioning defaults are currently compiled-in constants rather than environment variables. To change one, edit the corresponding constant in the circuit-breaker module or the decision-flow engine module and redeploy:

Default	Value
Max offers loaded per recommendation	5,000
Fallback score when model scoring fails	0.5
Daily limit on mandatory offer slots per customer	5

Tenant Configuration

Variable	Required	Description
`SINGLE_TENANT_MODE`	No	Set `true` to bypass tenant resolution (for single-tenant deploys)
`PLATFORM_OWNER_TENANT_ID`	No	Tenant ID for platform-level settings (default: `default`)
`INTERNAL_SERVICE_SECRET`	No	Shared secret for inter-service auth (falls back to `NEXTAUTH_SECRET`)

Worker

Variable	Required	Description
`WORKER_CONCURRENCY`	No	BullMQ worker concurrency (default: `5`)
`WORKER_METRICS_PORT`	No	Prometheus metrics port for worker (default: `9091`)

Deploy

Configure

Operate

Architecture

Runbooks

Deployment options

Cloud

Dedicated

Enterprise on-prem

Enterprise on-prem topologies

Local / evaluation

Managed cloud (App Runner)

Kubernetes (Helm)

Comparison of on-prem topologies

Docker Images

Environment Variables

Core (Required)

Security (Required in Production)

Authentication

Infrastructure

Observability

Security Headers

Decisioning Tuning

Tenant Configuration

Worker

Next Steps

Local Development

Cloud Deployment

Cloud

Dedicated

Enterprise on-prem

​Enterprise on-prem topologies

Local / evaluation

Managed cloud (App Runner)

Kubernetes (Helm)

​Comparison of on-prem topologies

​Docker Images

​Environment Variables

​Core (Required)

​Security (Required in Production)

​Authentication

​Infrastructure

​Observability

​Security Headers

​Decisioning Tuning

​Tenant Configuration

​Worker

​Next Steps

Local Development

Cloud Deployment

Enterprise on-prem topologies

Comparison of on-prem topologies

Docker Images

Environment Variables

Core (Required)

Security (Required in Production)

Authentication

Infrastructure

Observability

Security Headers

Decisioning Tuning

Tenant Configuration

Worker

Next Steps