Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.waniwani.ai/llms.txt

Use this file to discover all available pages before exploring further.

The SDK is open source and runs without an API key. The Platform is an optional hosted layer at app.waniwani.ai that adds features the engine alone doesn’t ship: event tracking, funnel analytics, a knowledge base, a chat widget, and hosted flow state. The Platform works the same whether your MCP server is on your own infra or on Managed Hosting. A single environment variable, WANIWANI_API_KEY, switches it on.

​
Two independent choices

Where your server runs and whether you connect the Platform are independent decisions:
No PlatformWith Platform
Self-hosted serverPure open source. Engine on your infra, no outbound calls.Your infra for the server, our backend for KB, chat, tracking, and (optionally) state.
Managed HostingNot applicable.Fully managed. We host the server and the Platform.
Pick the combination that fits. Most teams start at “self-hosted + Platform” or “Managed Hosting + Platform”, and a smaller set runs pure open source.

​
What the Platform adds

FeatureEntry pointWhat it gives you
Event trackingwithWaniwani(server), waniwani().track()tool.called events, custom events, dashboard ingest
Funnel analyticsAutomatic from tracked node visitsConversion, drop-off, completion rate per node
Knowledge base@waniwani/sdk/kbMarkdown ingest, semantic search from any tool
Chat widget@waniwani/sdk/chatDrop-in chat against your project, in script or React
Hosted flow stateWaniwaniKvStore (auto-selected)Encrypted-at-rest state with zero infra
All of these require WANIWANI_API_KEY. None of them require Managed Hosting.

​
Enable it

.env
WANIWANI_API_KEY=wwk_...
Create a free key at app.waniwani.ai. See API keys for staging vs production setup. With the key set, createFlow().compile() selects WaniwaniKvStore automatically when no store argument is passed, withWaniwani(server) starts emitting tracked events, and the KB / chat clients work end to end.

​
What works without it

The engine is fully usable with no key:
  • createFlow, StateGraph, START, END, redacted from @waniwani/sdk/mcp
  • KvStore interface and MemoryKvStore (plus any adapter you write for Redis, Upstash, Cloudflare KV, DynamoDB, SQLite)
  • withWaniwani(server) as a no-op wrapper that still bridges transport session IDs and forwards widget metadata
  • useWaniwani() browser hook in degrade-to-no-op mode
createFlow().compile() requires a store when no API key is configured. With neither, it throws at compile time: 
Error: [waniwani] createFlow "...": no flow store configured.
Pass { store } to .compile(). Use MemoryKvStore from "@waniwani/sdk/mcp"
for local development, or plug in a Redis/Upstash/Cloudflare KV adapter
for production. Alternatively, set WANIWANI_API_KEY to use hosted flow
state on app.waniwani.ai.
This is intentional. No silent fallback to a backend that does not exist in production. See self-hosting the engine for the fully offline path.

​
Going from open source to Platform

One line. Drop the store argument and set the env var: 
- .compile({ store: flowStore });
+ .compile(); // uses WaniwaniKvStore when WANIWANI_API_KEY is set
Existing sessions stay where they started: pre-switch sessions keep reading from your KV backend, new sessions persist on app.waniwani.ai. There is no automatic migration. To keep self-hosted state and only add Platform tracking on top, keep the explicit store and call withWaniwani(server). Tracking fires to app.waniwani.ai; flow state stays in your backend. The two pipelines are independent.

​
Pricing

The Platform has a free plan. Set the API key and you are in. Limits and paid plans are listed at app.waniwani.ai.