> ## 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.

# Waniwani Platform

> Optional hosted layer that adds tracking, knowledge base, chat widget, and hosted flow state to any MCP server you run.

The SDK is open source and runs without an API key. The **Platform** is an optional hosted layer at [app.waniwani.ai](https://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](/sdk/deployment/overview). 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 Platform                                                | With Platform                                                                          |
| ---------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Self-hosted server** | Pure open source. Engine on your infra, no outbound calls. | Your infra for the server, our backend for KB, chat, tracking, and (optionally) state. |
| **Managed Hosting**    | Not 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

| Feature           | Entry point                                                                                              | What it gives you                                     |
| ----------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Event tracking    | [`withWaniwani(server)`](/sdk/configuration/wrap-server), [`waniwani().track()`](/sdk/tracking/overview) | `tool.called` events, custom events, dashboard ingest |
| Funnel analytics  | Automatic from tracked node visits                                                                       | Conversion, drop-off, completion rate per node        |
| Knowledge base    | [`@waniwani/sdk/kb`](/sdk/knowledge-base/overview)                                                       | Markdown ingest, semantic search from any tool        |
| Chat widget       | [`@waniwani/sdk/chat`](/sdk/chat/embed)                                                                  | Drop-in chat against your project, in script or React |
| Hosted flow state | [`WaniwaniKvStore`](/sdk/flows/kv-store) (auto-selected)                                                 | Encrypted-at-rest state with zero infra               |

All of these require `WANIWANI_API_KEY`. None of them require Managed Hosting.

## Enable it

```bash .env theme={null}
WANIWANI_API_KEY=wwk_...
```

[Create a free key at app.waniwani.ai](https://app.waniwani.ai). See [API keys](/sdk/configuration/api-key) 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](/sdk/deployment/self-hosting) for the fully offline path.

## Going from open source to Platform

One line. Drop the `store` argument and set the env var:

```diff theme={null}
- .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](https://app.waniwani.ai).