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

# Deployment

> Run your Waniwani-powered MCP app on Managed Hosting or self-host it yourself (Docker, Alpic, Vercel).

Where your MCP server runs is independent of whether you connect the [Waniwani Platform](/sdk/platform/overview). This page covers the two server-hosting options. The Platform layer (tracking, KB, chat, hosted state) works the same in both.

<CardGroup cols={2}>
  <Card title="Managed Hosting" icon="cloud" href="#managed-hosting">
    Waniwani hosts your app. Provisioned, pre-configured, push to main and it deploys. Fastest path.
  </Card>

  <Card title="Self-hosted" icon="server" href="#self-hosted-server">
    You host the app yourself. Docker, Alpic, or Vercel. Connect by giving us the MCP URL.
  </Card>
</CardGroup>

Both paths use the same [MCP Distribution Template](https://github.com/WaniWani-AI/mcp-distribution-template). Pick based on where you want the server to live.

## Managed Hosting

When you create a managed project in the [Waniwani dashboard](https://app.waniwani.ai), we provision a copy of the distribution template fully wired up: API keys set, hosted URL assigned, everything ready. You don't configure anything.

Typical workflow:

<Steps>
  <Step title="Create the project">
    From [app.waniwani.ai](https://app.waniwani.ai), create a managed project. We spin up a repo from the template and deploy it on our managed hosting. Your tools, flows, widgets, and chat surface are live immediately.
  </Step>

  <Step title="Take ownership of the code">
    Move the provisioned repo into your own GitHub organization when you want full control over the codebase. You keep the managed hosting; you just own the source now.
  </Step>

  <Step title="Push to main">
    Every push to `main` auto-deploys to our managed hosting environment. API keys, URLs, and tracking continue to flow without any setup on your side.
  </Step>
</Steps>

Best for: getting started fast, teams that don't want to run infrastructure, and projects that want one less moving part to maintain.

## Self-hosted server

You run the server. By default we recommend connecting the [Platform](/sdk/platform/overview): set `WANIWANI_API_KEY` and you get hosted state + dashboards on top of your self-hosted server, with no extra infra. If you want to push that further and self-host the state layer too, see [Advanced: bring your own session cache](#advanced-bring-your-own-session-cache) below. If you want zero Platform dependency at all (no API key, no outbound calls), see the [open-source self-hosting walkthrough](/sdk/deployment/self-hosting).

The [MCP Distribution Template](https://github.com/WaniWani-AI/mcp-distribution-template) ships three deployment targets. Pick whichever fits your stack.

<CardGroup cols={3}>
  <Card title="Docker" icon="box" href="#docker">
    Run anywhere a container runs.
  </Card>

  <Card title="Alpic" icon="bolt" href="#alpic">
    MCP-native runtime.
  </Card>

  <Card title="Vercel" icon="triangle" href="#vercel">
    One command from the template root.
  </Card>
</CardGroup>

### Docker

The template ships a `Dockerfile`. Build and run anywhere a container runs (Fly.io, Render, Railway, ECS, GCP Cloud Run, your own VPS, Kubernetes).

```bash theme={null}
docker build -t my-mcp-app .
docker run --env-file .env -p 3000:3000 my-mcp-app
```

Set `WANIWANI_API_KEY` and any backend secrets in the runtime's environment.

### Alpic

Deploy to [Alpic](https://github.com/alpic-ai/skybridge), an MCP-native hosting runtime. Follow Alpic's deployment instructions for the template repo. The SDK is tested against the Skybridge runtime, so flows, tracking, and widgets work out of the box.

### Vercel

```bash theme={null}
vercel deploy
```

From the template root. Set `WANIWANI_API_KEY` and any backend secrets in your Vercel project's environment variables.

### Connect to Waniwani

Once your app is deployed, copy its public MCP URL (the endpoint where MCP clients send `initialize` / `tools/call` requests). In the Waniwani dashboard, create a self-hosted project and paste that URL. Waniwani uses it as the entry point for chat requests, widget rendering, and analytics ingestion.

### Advanced: bring your own session cache

By default a self-hosted server uses `WaniwaniKvStore` for flow state when `WANIWANI_API_KEY` is set (encrypted at rest, hosted by Waniwani, no infra). That's the recommended setup.

If you want zero dependency on `app.waniwani.ai` for state too, plug in your own `KvStore` adapter at `.compile()` time:

```ts theme={null}
import { createFlow } from "@waniwani/sdk/mcp";
import { flowStore } from "./kv-store"; // your Redis / Upstash / DynamoDB / SQLite adapter

const flow = createFlow({ /* ... */ }).compile({ store: flowStore });
```

See [KV store adapters](/sdk/flows/kv-store) for recipes (Redis, Upstash, Cloudflare KV, DynamoDB, SQLite) and the full [open-source self-hosting](/sdk/deployment/self-hosting) walkthrough.

Your server, your state. You can still send tracking events to the Platform by calling `withWaniwani(server)`, or skip that entirely for a fully open-source setup.

## Platform features are orthogonal

Tracking, KB, chat, funnel analytics, and hosted state are Platform features. They are independent of where your server lives and where your state lives. Both Managed Hosting and self-hosted servers emit events through `withWaniwani(server)` and `client.track()`, and both surface in the same Waniwani dashboard. See the [Platform overview](/sdk/platform/overview) for what's included and [Tracking](/sdk/tracking/overview) for the event pipeline.