Self-host quickstart

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 locally with 10 Starbucks 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 (Fastest)
Docker Compose
Local Development

No setup needed. Use the hosted playground to explore KaireonAI instantly.

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 playground comes pre-loaded with sample data (Starbucks dataset) — 10 offers, 6 channels, scoring models, and a complete Decision Flow. You are ready to make your first recommendation.

Playground accounts have usage limits: 100 API requests/minute, 5,000 lifetime decisions, and entity caps (50 offers, 10 schemas, 5 pipelines). Self-host for unlimited usage.

Clone and configure

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

Start everything

docker compose up

This starts PostgreSQL, Redis, and the KaireonAI platform. Wait for Ready on http://localhost:3000.

Open the platform

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

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

Start the dev server

npm run dev

Visit http://localhost:3000 and sign in with admin@kaireonai.com / admin123.

Load Sample Data

With the platform running, load the Starbucks 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 Starbucks dataset

Click Load next to the Starbucks 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
Qualification Rules	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 Starbucks dataset is designed as a complete learning environment. Every entity is connected — offers have creatives linked to channels, qualification rules 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": "starbucks-offers",
  "decisionFlowVersion": 1,
  "experimentVariant": null,
  "controlGroup": false,
  "timestamp": "2026-04-14T12:00:00.000Z",
  "channel": "all",
  "placement": "all",
  "count": 3,
  "decisions": [
    {
      "offerId": "92a89bed-...",
      "offerName": "Starbucks: Discount — 10 Day Low",
      "creativeName": "Starbucks: Discount Low — Social",
      "channelName": "Starbucks: Social",
      "categoryName": "Starbucks: Retention",
      "score": 1,
      "rank": 1,
      "content": {
        "post": "Treat yourself to our Discount Low offer!",
        "hashtags": ["#Starbucks", "#StarbucksRewards"]
      },
      "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 Starbucks 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?

Starbucks Tutorial

Build the entire Starbucks 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

Self-host quickstart

Prerequisites

Docker Compose (Recommended)

Local Development

Setup

Load Sample Data

Run Your First Recommendation

What Just Happened?

What’s Next?

Starbucks Tutorial

Try the AI Assistant

Decision Flows

API Reference

Deploy

Configure

Operate

Architecture

Runbooks

Documentation Index

​Prerequisites

Docker Compose (Recommended)

Local Development

​Setup

​Load Sample Data

​Run Your First Recommendation

​What Just Happened?

​What’s Next?

Starbucks Tutorial

Try the AI Assistant

Decision Flows

API Reference

Prerequisites

Setup

Load Sample Data

Run Your First Recommendation

What Just Happened?

What’s Next?