> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment quickstart

> Evaluate KaireonAI free on the hosted Playground, then move to a Cloud, Dedicated, or Enterprise on-prem plan.

<Note>
  **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](/self-host/deploy/options) and [contact sales](mailto:sales@kaireonai.com).
</Note>

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

<CardGroup cols={2}>
  <Card title="Docker Compose (Recommended)" icon="docker">
    Just Docker Desktop installed. Everything else (PostgreSQL, Redis) runs in containers.
  </Card>

  <Card title="Local Development" icon="terminal">
    **Node.js 22+**, **PostgreSQL 15+**, and optionally **Redis**. For contributors or if you want Turbopack hot-reload.
  </Card>
</CardGroup>

***

## Setup

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

<Tabs>
  <Tab title="Playground (Free trial)">
    No setup needed. Use the hosted Playground — the free trial — to explore KaireonAI instantly before you buy.

    <Steps>
      <Step title="Create an account">
        Go to [playground.kaireonai.com](https://playground.kaireonai.com/register) and create an account with your email and a password. No email verification needed — you can sign in immediately.
      </Step>

      <Step title="Sign in">
        Go to [playground.kaireonai.com/login](https://playground.kaireonai.com/login) and sign in with your credentials. You can also use **Continue with Google** for one-click access.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    <Info>
      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](/self-host/deploy/options).
    </Info>
  </Tab>

  <Tab title="Docker Compose">
    <Info>
      **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](mailto:sales@kaireonai.com) to get started.
    </Info>

    <Steps>
      <Step title="Clone and configure">
        ```bash theme={null}
        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).
      </Step>

      <Step title="Start everything">
        ```bash theme={null}
        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.

        <Warning>
          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`.
        </Warning>
      </Step>

      <Step title="Open the platform">
        Visit [http://localhost:3000](http://localhost:3000) and register a new account.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Local Development">
    <Info>
      **Enterprise-licensed / internal development.** Source access is provisioned under a commercial Enterprise license. [Contact sales](mailto:sales@kaireonai.com).
    </Info>

    <Steps>
      <Step title="Clone and install">
        ```bash theme={null}
        git clone https://github.com/kaireonai/platform.git
        cd platform
        npm install
        ```
      </Step>

      <Step title="Configure environment">
        ```bash theme={null}
        cp .env.example .env
        ```

        Edit `.env` with your database connection:

        ```env theme={null}
        DATABASE_URL=postgresql://user:password@localhost:5432/kaireon
        REDIS_URL=redis://localhost:6379
        NEXTAUTH_SECRET=any-random-string-for-local-dev
        ```

        <Info>
          `REDIS_URL` is optional. Without it, the platform skips Redis-backed caching and rate limiting — everything still works.
        </Info>
      </Step>

      <Step title="Initialize the database">
        ```bash theme={null}
        npx prisma generate
        npx prisma db push
        ```

        <Warning>
          `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.
        </Warning>
      </Step>

      <Step title="Start the dev server">
        ```bash theme={null}
        npm run dev
        ```

        Visit [http://localhost:3000](http://localhost:3000) and register a new account. Local development does not seed a default admin user.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## 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](#run-your-first-recommendation).

<Steps>
  <Step title="Navigate to Settings > Sample Data">
    Click **Settings** in the sidebar, then select **Sample Data**.
  </Step>

  <Step title="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                        |
  </Step>

  <Step title="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).
  </Step>
</Steps>

<Tip>
  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.
</Tip>

***

## Run Your First Recommendation

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

<Tabs>
  <Tab title="Playground">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Local">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

<Tip>
  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.
</Tip>

**Expected response (trimmed):**

```json theme={null}
{
  "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
  }
}
```

<Tip>
  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.
</Tip>

***

## What Just Happened?

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

1. **Inventory** -- Loaded all 10 offers with their 60 creatives
2. **Qualification** -- Filtered out offers the customer is not eligible for based on rules
3. **Contact Policy** -- Removed offers that would violate frequency caps
4. **Scoring** -- Evaluated remaining candidates using the sample retail scorecard model
5. **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?

<CardGroup cols={2}>
  <Card title="Retail Rewards Tutorial" icon="play" href="/get-started/walkthrough">
    Build the entire retail rewards pipeline from scratch — step by step, entity by entity. The best way to learn KaireonAI.
  </Card>

  <Card title="Try the AI Assistant" icon="sparkles" href="/tutorials/try-ai-assistant">
    Ask the AI assistant about your data: "How many offers do I have?" or "Create a new email channel."
  </Card>

  <Card title="Decision Flows" icon="diagram-project" href="/decisioning/decision-flows">
    Learn how the composable pipeline works — 16 node types, visual canvas editor, PRIE scoring.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/recommend">
    Full Recommend and Respond API documentation with request/response schemas.
  </Card>
</CardGroup>