Local Development

Running KaireonAI yourself is an Enterprise offering under a commercial license. Source and image access is provisioned as part of an Enterprise agreement — this is not a free or open download. Contact sales. To evaluate the platform at no cost, use the hosted Playground.

Prerequisites

Dependency	Version	Required
Node.js	22+	Yes
PostgreSQL	14+	Yes
Python	3.11+	No (for ML Worker)
Redis	6+	No (recommended)

Install PostgreSQL

macOS
Ubuntu/Debian
Docker

brew install postgresql@16
brew services start postgresql@16
createdb kaireon

sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo -u postgres createdb kaireon

docker run -d --name kaireon-pg \
  -e POSTGRES_DB=kaireon \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:16

Install Redis (Optional)

KaireonAI uses Redis for enrichment data caching and API rate limiting. Without it, the platform runs fine but skips these features.

macOS
Ubuntu/Debian
Docker

brew install redis
brew services start redis

sudo apt install redis-server
sudo systemctl start redis-server

docker run -d --name kaireon-redis -p 6379:6379 redis:7-alpine

Platform Setup

Clone and install

git clone https://github.com/kaireonai/platform.git
cd platform
npm install

Create .env file

cp .env.example .env

Edit .env:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kaireon
REDIS_URL=redis://localhost:6379
NEXTAUTH_SECRET=local-dev-secret-change-in-production

Initialize the database

npx prisma generate
npx prisma db push
npx tsx prisma/seed.ts

The seed script creates the default tenant and an admin user:

Email: admin@kaireonai.com
Password: admin123

prisma db push is safe only on a fresh database. On a populated database it drops any table not defined in schema.prisma — including the runtime-created ds_* customer-schema tables and _flow_* pipeline staging tables — which means data loss. Once you have real data, evolve the schema with the numbered files in prisma/manual-sql/ applied via psql, not db push.

Start the development server

npm run dev

Open http://localhost:3000 and sign in with the admin credentials.

ML Worker Setup (Optional)

The ML Worker provides scikit-learn-based analysis for AI features. It’s optional — all AI features fall back to LLM-based analysis without it.

Set up environment

cd ml-worker
cp .env.example .env

Edit ml-worker/.env to match your local database:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kaireon

Install Python dependencies

pip install -r requirements.txt

Start the ML Worker

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Connect the platform

Add to platform/.env:

ML_WORKER_URL=http://localhost:8000

Restart the Next.js dev server. The AI > Insights page should show “ML Worker Connected”.

Docker Compose (Full Stack)

Run the entire stack with Docker Compose instead of installing each dependency. The docker-compose.yml lives at the repository root:

cp .env.example .env   # set POSTGRES_PASSWORD and NEXTAUTH_SECRET at minimum

# Platform only
docker compose up -d

# Platform + ML Worker (ml profile)
docker compose --profile ml up -d

This starts PostgreSQL, PgBouncer, Redis, the API, the background worker, and optionally the ML Worker, with the app served on http://localhost:3000. The API entrypoint waits for the database, runs npx prisma db push --skip-generate to sync the schema, then starts the server.

The Compose api and worker services run with NODE_ENV=production, so the platform’s startup validation requires a full set of production security secrets. The shipped docker-compose.yml now provides working dev-only defaults for all of them (via ${VAR:-default} substitutions in a shared x-app-secrets block), so docker compose up starts cleanly with no configuration.The required variables are NEXTAUTH_SECRET, JWT_SIGNING_SECRET, CONNECTOR_ENCRYPTION_KEY, WEBHOOK_SIGNING_SECRET, API_KEY_PEPPER, and a non-wildcard CORS_ALLOWED_ORIGINS. The baked-in defaults are not secret — anyone can read them in the repo — so before exposing the stack to anyone else, override each one (plus POSTGRES_PASSWORD). Because they use ${VAR:-...} substitution, Compose interpolates any value you export in your shell or set in .env, so you no longer need to edit the Compose file:

# .env — overrides the dev-only defaults baked into docker-compose.yml
POSTGRES_PASSWORD=...
NEXTAUTH_SECRET=...
JWT_SIGNING_SECRET=...
CONNECTOR_ENCRYPTION_KEY=...
WEBHOOK_SIGNING_SECRET=...
API_KEY_PEPPER=...
CORS_ALLOWED_ORIGINS=https://your-app.example.com

CORS_ALLOWED_ORIGINS must be set and must not be *. Generate strong secrets with openssl rand -hex 32. See the environment variable reference for details.

The ML Worker includes a health check (/health on port 8000) that Docker runs on a schedule. Check its reported status — healthy, unhealthy, or starting — with docker compose ps.

Verify Installation

After signing in, check the home dashboard — you should see cards for Decision Flows, Offers, Channels, etc. all at zero counts. To load demo content, go to Settings → Sample Data and load the Retail Rewards dataset. This will populate the platform with schemas, offers, channels, models, and creatives.

Running Tests

npm test              # Run tests in watch mode
npm run test:coverage # Run with coverage report
npm run build         # Type-check + production build

Troubleshooting

Prisma 7: 'The datasource property url is no longer supported'

Prisma 7 moved the connection URL out of schema.prisma and into prisma.config.ts. If you see this error, remove the url = env("DATABASE_URL") line from prisma/schema.prisma. The datasource block should only contain provider = "postgresql". The connection URL is configured in prisma.config.ts.

Port 3000 already in use

Another process is using port 3000. Find and stop it:

lsof -ti:3000 | xargs kill -9
npm run dev

Alternatively, start on a different port:

PORT=3001 npm run dev

Redis connection refused (optional dependency)

Redis is optional for local development. If Redis is not running, the platform skips enrichment caching, rate limiting, and circuit breaker features but otherwise works normally. To suppress connection warnings, remove REDIS_URL from your .env file. To install Redis, see the Install Redis section above.

npx prisma generate fails with 'Cannot find module'

Ensure you are running commands from the platform/ directory (not the repo root). The Prisma 7 config expects prisma.config.ts in the working directory:

cd platform
npx prisma generate

NEXTAUTH_SECRET warning in development

The platform warns if NEXTAUTH_SECRET is not set in development. Auth features (login, session management) will not work correctly without it. Add any random string to your .env:

NEXTAUTH_SECRET=local-dev-secret-change-in-production

Next Steps

Platform Walkthrough

Build a complete decisioning setup step by step.

Cloud Deployment

Ready for production? Deploy to AWS App Runner.

Kubernetes

Deploy to any Kubernetes cluster using the Helm chart.

ML Worker

Add the Python ML Worker for AI-powered analysis.

Deploy

Configure

Operate

Architecture

Runbooks

Prerequisites

Install PostgreSQL

Install Redis (Optional)

Platform Setup

ML Worker Setup (Optional)

Docker Compose (Full Stack)

Verify Installation

Running Tests

Troubleshooting

Next Steps

Platform Walkthrough

Cloud Deployment

Kubernetes

ML Worker

​Prerequisites

​Install PostgreSQL

​Install Redis (Optional)

​Platform Setup

​ML Worker Setup (Optional)

​Docker Compose (Full Stack)

​Verify Installation

​Running Tests

​Troubleshooting

​Next Steps

Platform Walkthrough

Cloud Deployment

Kubernetes

ML Worker

Prerequisites

Install PostgreSQL

Install Redis (Optional)

Platform Setup

ML Worker Setup (Optional)

Docker Compose (Full Stack)

Verify Installation

Running Tests

Troubleshooting

Next Steps