finic-ai/kairos

What it does

Kairos makes a decision on each sign-up, login, order, payment or payout as it happens, returning approve, step up, review or block along with a risk score and the reasons behind it. It is positioned as an open-source alternative to commercial fraud platforms such as Sardine, Sift, Riskified and SEON.

The decision path draws on the subject's history, shared devices, cards and addresses, and session signals. Workflows can query a decision model, score with a model, branch, call webhooks, open cases and decide again later, while review queues turn human resolutions into labels for training (decisions, workflows, queues).

Two model paths coexist: Grayson, Finic's hosted decision model that answers plain-language questions with calibrated probabilities, and traditional models (logistic regression and XGBoost-compatible gradient-boosted trees) trained inside Kairos on your data. Their outputs can be combined as features in one model, and experiments compare variants on time-split data.

An MCP server lets coding agents such as Claude Code, Cursor or Codex read decisions, build workflows and propose model variants; each action is recorded under its own key (MCP docs, models).

Quick start

The fastest route is the hosted option: sign up at the Kairos Cloud console, create a sandbox environment and a secret key, then install an SDK and send events.

npm install @finic-ai/kairos      # or: pip install finic-kairos

import { Kairos } from "@finic-ai/kairos";

const kairos = new Kairos({ apiKey: process.env.KAIROS_API_KEY!, baseUrl: "https://kairos.finic.ai" });

await kairos.defineAction("withdrawal", {
  subject: "user",
  hold: "Should this withdrawal be held because the account shows signs of fraud or takeover?",
});

kairos.track("login", { userId: "user_42", deviceId: "dev_9", ipCountry: "GB" });

const decision = await kairos.decide({ type: "withdrawal", userId: "user_42", usd: 900 });
// { decision: "approve" | "step_up" | "review" | "block", riskScore, reasons, … }

The README's example asks the agent to design six variants, read the experiment results and publish the winning one as the next workflow version. For more detail, see the quickstart and the TypeScript SDK reference.

Self-hosting

Self-hosting needs Node.js 22, pnpm 10 and a Grayson API key from the Finic portal. According to the README, no database setup is required because the server starts its own Postgres.

pnpm install
cp .env.example .env     # set GRAYSON_API_KEY
pnpm kairos dev          # API on http://localhost:8787, console on http://localhost:5273

For teams, docker compose up --build is documented as the deployment route; configuration, migrations and security notes are in the self-hosting guide. The repository also exposes a CLI for signing up, creating keys, defining actions, importing events and running decisions or workflows (CLI docs).

Constraints

• The self-hosted path depends on a Grayson API key from Finic, so even local deployments rely on an external model service for that portion of scoring.
• The Node.js 22 and pnpm 10 requirements are stated for local development; the Docker route is the documented team option.
• Decisions are only as useful as the event history and labels you send in; the README frames existing events, customers and outcomes as importable via the history import flow (import history).
• The hosted service and the repository are distinct: cloud sign-up, MCP keys and sandbox environments live in the console, while the code is Apache-2.0 licensed.

HotRepo's take

Kairos was created on 2026-10-30 and appeared on HotRepo's new-project list for TypeScript on 2026-11-04, with 113 stars and 6 forks; the recorded growth window showed 7 stars and 2 forks added in about an hour. The same period contains a Show HN thread titled "Show HN: Kairos – Open-source risk and fraud decisioning platform" with 76 points and 15 comments (HN thread).

The comments are mostly general: one reader calls the real-time flow worth showing, and another digs into the word "decisioning," a term that is already established in the fraud industry (comment). Neither the star count nor the discussion establishes adoption or effectiveness; what the repository itself supports is a concrete decisioning stack (API, SDKs, CLI, console, MCP integration and self-hosting) rather than a landing page.