Deployment quickstart

Running KaireonAI yourself (on-prem) is an Enterprise offering under a commercial license — it is not a free or open download. The Docker Compose and local-development instructions in this section are for licensed Enterprise customers and internal development; image and source access is provisioned as part of an Enterprise agreement. To evaluate the platform at no cost, start with the hosted Playground below. For production, most teams run on the fully hosted Cloud plan. See Deployment options and contact sales.

This guide gets you from zero to a working decisioning platform with sample data and a live API call. By the end, you will have KaireonAI running with 10 sample retail offers, 6 channels, scoring models, and a complete Decision Flow — and you will have called the Recommend API to get personalized results.

Prerequisites

Docker Compose (Recommended)

Just Docker Desktop installed. Everything else (PostgreSQL, Redis) runs in containers.

Local Development

Node.js 22+, PostgreSQL 15+, and optionally Redis. For contributors or if you want Turbopack hot-reload.

Setup

Choose your path — both get you to the same result.

Playground (Free trial)
Docker Compose
Local Development

No setup needed. Use the hosted Playground — the free trial — to explore KaireonAI instantly before you buy.

Create an account

Go to playground.kaireonai.com and create an account with your email and a password. No email verification needed — you can sign in immediately.

Go to playground.kaireonai.com/login and sign in with your credentials. You can also use Continue with Google for one-click access.

Explore

Your workspace comes pre-loaded with the sample retail dataset — 10 offers, 6 channels, scoring models, and a complete Decision Flow. You are ready to make your first recommendation.

Playground trial workspaces have limits: 100 API requests/minute, 5,000 lifetime decisions, and entity caps (50 offers, 10 schemas, 5 pipelines). For production volume, move to a paid plan — see Deployment options.

Enterprise-licensed. Running the platform yourself is available under a commercial Enterprise license; image and source access is provisioned as part of your agreement. Contact sales to get started.

Clone and configure

git clone https://github.com/kaireonai/platform.git
cd platform
cp .env.example .env

The Compose file boots with built-in dev-only defaults, so docker compose up works with no edits at all. For anything beyond local experimentation, set POSTGRES_PASSWORD and override every production secret in .env (see the warning below).

Start everything

docker compose up -d

This starts PostgreSQL, PgBouncer, Redis, the KaireonAI API, and the worker. The API container’s health check polls /api/ready; wait until it reports healthy, then open the app.

The api and worker services run with NODE_ENV=production, so the platform’s strict startup env-validation requires a full set of secrets: NEXTAUTH_SECRET, JWT_SIGNING_SECRET, CONNECTOR_ENCRYPTION_KEY, WEBHOOK_SIGNING_SECRET, API_KEY_PEPPER, and a non-wildcard CORS_ALLOWED_ORIGINS. The shipped docker-compose.yml now provides working dev-only default values for all of these, so docker compose up starts cleanly with no configuration. Those defaults are not secret — anyone can read them in the repo — so before you expose the stack to anyone else, override each one (and POSTGRES_PASSWORD) by exporting the variable or setting it in .env. Generate strong values with openssl rand -hex 32.

Open the platform

Visit http://localhost:3000 and register a new account.

Enterprise-licensed / internal development. Source access is provisioned under a commercial Enterprise license. Contact sales.

Clone and install

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

Configure environment

cp .env.example .env

Edit .env with your database connection:

DATABASE_URL=postgresql://user:password@localhost:5432/kaireon
REDIS_URL=redis://localhost:6379
NEXTAUTH_SECRET=any-random-string-for-local-dev

REDIS_URL is optional. Without it, the platform skips Redis-backed caching and rate limiting — everything still works.

Initialize the database

npx prisma generate
npx prisma db push

prisma db push is safe only on a fresh database. On a populated database it drops any tables not modeled in schema.prisma — including the runtime-created ds_* customer-schema tables and _flow_* pipeline staging tables — which causes data loss. Use it only for first-time local setup.

Start the dev server

npm run dev

Visit http://localhost:3000 and register a new account. Local development does not seed a default admin user.

Load Sample Data

With the platform running, load the sample retail dataset to see everything in action. Playground users already have sample data pre-loaded — skip to Run Your First Recommendation.

Navigate to Settings > Sample Data

Click Settings in the sidebar, then select Sample Data.

Load the retail rewards dataset

Click Load next to the retail rewards dataset. This creates:

Entity	Count	Examples
Offers	10	BOGO Frappuccino, 25% Off Merchandise, Earn 3x Stars
Channels	6	Web, Email, Mobile Push, Social, Batch Email, Manual Outreach
Creatives	60	Content variants per offer per channel
Scoring Models	3	Scorecard, Bayesian, Thompson Bandit
Decision Flow	1	Complete pipeline with qualification, scoring, and ranking
Decisioning Gates	Yes	Eligibility gates based on customer attributes
Contact Policies	Yes	Frequency caps to prevent over-contact

Verify on the Home page

Go to the Home page. You should see entity counts populated: 1 Decision Flow, 10 Offers, 6 Channels, and three scoring algorithms (Scorecard, Bayesian, Thompson Bandit).

The retail rewards dataset is designed as a complete learning environment. Every entity is connected — offers have creatives linked to channels, decisioning gates reference customer attributes, and the Decision Flow ties it all together.

Run Your First Recommendation

Call the Recommend API to see the decision engine evaluate, score, and rank offers for a specific customer.

Playground
Local

curl -s -X POST https://playground.kaireonai.com/api/v1/recommend \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: YOUR_TENANT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "customerId": "SBX-000042",
    "limit": 3
  }' | python3 -m json.tool

curl -s -X POST http://localhost:3000/api/v1/recommend \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: YOUR_TENANT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "customerId": "SBX-000042",
    "limit": 3
  }' | python3 -m json.tool

Find your Tenant ID and API Key in Settings > API Explorer. Both are auto-populated from your session. Click Manage Keys to create additional keys or revoke existing ones. On the playground, a default API key is created automatically when you register.

Expected response (trimmed):

{
  "interactionId": "095baa57-...",
  "recommendationId": "095baa57-...",
  "customerId": "SBX-000042",
  "decisionFlowKey": "retail-rewards",
  "decisionFlowVersion": 1,
  "experimentVariant": null,
  "controlGroup": false,
  "timestamp": "2026-04-14T12:00:00.000Z",
  "channel": "all",
  "placement": "all",
  "count": 3,
  "decisions": [
    {
      "offerId": "92a89bed-...",
      "offerName": "Retail Rewards: Discount — 10 Day Low",
      "creativeName": "Retail Rewards: Discount Low — Social",
      "channelName": "Retail Rewards: Social",
      "categoryName": "Retail Rewards: Retention",
      "score": 1,
      "rank": 1,
      "content": {
        "post": "Treat yourself to our Discount Low offer!",
        "hashtags": ["#RetailRewards", "#MemberOffers"]
      },
      "scoreExplanation": {
        "method": "priority_weighted",
        "priority": 85,
        "finalScore": 1
      }
    }
  ],
  "meta": {
    "totalCandidates": 60,
    "afterQualification": 60,
    "afterSuppression": 60,
    "afterContactPolicy": 57,
    "degradedScoring": false
  }
}

The exact offers and scores depend on the scoring model and the customer attributes you pass. Try changing income to 120000 or age to 55 to see different results — the model adapts to each customer profile.

What Just Happened?

Behind that single API call, the decision engine ran a complete pipeline:

Inventory — Loaded all 10 offers with their 60 creatives
Qualification — Filtered out offers the customer is not eligible for based on rules
Contact Policy — Removed offers that would violate frequency caps
Scoring — Evaluated remaining candidates using the sample retail scorecard model
Ranking — Sorted by score and returned the top 3

This entire process completed in under 50ms. In production, you would call this API from your app, website, or email system whenever you need to decide what to show a customer.

What’s Next?

Retail Rewards Tutorial

Build the entire retail rewards pipeline from scratch — step by step, entity by entity. The best way to learn KaireonAI.

Try the AI Assistant

Ask the AI assistant about your data: “How many offers do I have?” or “Create a new email channel.”

Decision Flows

Learn how the composable pipeline works — 16 node types, visual canvas editor, PRIE scoring.

API Reference

Full Recommend and Respond API documentation with request/response schemas.

Deploy

Configure

Operate

Architecture

Runbooks

Deployment quickstart

Prerequisites

Docker Compose (Recommended)

Local Development

Setup

Load Sample Data

Run Your First Recommendation

What Just Happened?

What’s Next?

Retail Rewards Tutorial

Try the AI Assistant

Decision Flows

API Reference

​Prerequisites

Docker Compose (Recommended)

Local Development

​Setup

​Load Sample Data

​Run Your First Recommendation

​What Just Happened?

​What’s Next?

Retail Rewards Tutorial

Try the AI Assistant

Decision Flows

API Reference

Prerequisites

Setup

Load Sample Data

Run Your First Recommendation

What Just Happened?

What’s Next?