---
title: Installation
description: Get khotan-data running in your Next.js + Drizzle + Postgres project.
section: Get Started
url: /docs/installation
---

# Installation

This guide installs khotan-data in the order that matches the package today: package first, core runtime second, schema third, then the components you actually want to use.

khotan-data is opinionated toward Vercel-style Next.js deployments. The runtime works locally in any standard Next.js app, but the default durable workflow and scheduled-flow story assumes Vercel Workflow plus a single dispatcher cron in `vercel.json`.

## Prerequisites

- A Next.js App Router project
- TypeScript
- Drizzle ORM
- Postgres

If you are starting from a fresh app, `npx khotan init --full` can install the base Drizzle and shadcn dependencies for you.

## 1. Install the package

```terminal
$ npm i khotan-data
```

## 2. Set environment variables

| Variable | Purpose |
|---|---|
| `DATABASE_URL` | Postgres connection string used by Drizzle |
| `KHOTAN_SECRET` | Encrypts stored plug vars and wire vars |
| `KHOTAN_WEBHOOK_URL` | Public origin used when the `wire` command builds default callback URLs |
| `KHOTAN_DEBUG` | Enables plug debugging routes and the `khotan plug` CLI |
| `CRON_SECRET` | Optional bearer secret for the built-in `/api/khotan/cron` dispatcher route |

Generate a secret with `openssl rand -base64 32`.

### Example

```env
# .env.local (dev)
DATABASE_URL=postgres://...
KHOTAN_SECRET=...
KHOTAN_WEBHOOK_URL=https://abc123.ngrok.app
KHOTAN_DEBUG=1
CRON_SECRET=...
```

`KHOTAN_WEBHOOK_URL` can point at a tunnel in development while your app still runs on localhost. That is the easiest way to test real webhooks.

## 3. Initialize khotan and install built-in skills

```terminal
$ npx khotan init --yes
```

This scaffolds the core runtime and auto-accepts the prompt to install khotan's built-in agent skills.

| File | Purpose |
|---|---|
| `khotan.config.ts` | CLI config, including `outputDir` |
| `src/khotan/khotan.ts` or `khotan/khotan.ts` | Your khotan factory config |
| `app/api/khotan/[...all]/route.ts` | Catch-all API route that mounts the khotan REST handler |
| `AGENTS.md` | Root router that points agents at khotan skills |

When skills are installed, the CLI writes them into the agent directories it detects in the project:

- Cursor: `.cursor/skills/...`
- Claude Code: `.claude/skills/...`
- Codex: `.agents/skills/...`
- Copilot: `.github/skills/...`
- Kiro: `.kiro/skills/...`
- Roo: `.roo/rules/...`

If no agent directories exist yet, khotan defaults to Cursor plus Claude Code.

## 4. Add the schema files

```terminal
$ npx khotan add schema --yes
```

This writes khotan's standard Drizzle tables into your schema directory and updates your Drizzle setup so those tables are included.

Core tables include:

- `khotan_plugs`
- `khotan_resources`
- `khotan_flows`
- `khotan_wires`
- `khotan_webhook_handlers`
- `khotan_webhook_events`
- `khotan_runs`
- `khotan_mappings`

## 5. Run migrations

```terminal
$ npx khotan migrate
```

Use `npx khotan migrate --push` if you want Drizzle push mode instead of migration files.

## 6. Add the first components

Pick the components you need. A common first pass looks like this:

```terminal
$ npx khotan add plug --yes
$ npx khotan add inflow --yes
$ npx khotan add wire --yes
$ npx khotan add catch --yes
$ npx khotan add hub --yes
$ npx khotan add runs --yes
```

These commands scaffold files into:

- `src/khotan/` or `khotan/` for runtime builders
- `src/components/khotan/` or `components/khotan/` for React components
- `src/app/` or `app/` for ready-made page blocks

## 7. Add a ready-made page block

```terminal
$ npx khotan add config-page-1
```

This creates a `/config` page that renders the Hub.

Other ready-made blocks:

```terminal
$ npx khotan add graph
$ npx khotan add logs-page-1
$ npx khotan add debug-page-1
```

## 8. Add the dispatcher cron for production

Add one cron entry to `vercel.json`:

```json
{
  "crons": [
    { "path": "/api/khotan/cron", "schedule": "* * * * *" }
  ]
}
```

This is the recommended deployment pattern. Keep per-flow schedules in `khotan.ts`, and let `/api/khotan/cron` decide which flows are due on each tick. If `CRON_SECRET` is set, Vercel should call the route with `Authorization: Bearer <CRON_SECRET>`.

## 9. Verify the runtime

Start your app, then confirm the runtime is mounted:

```terminal
$ curl http://localhost:3000/api/khotan/plugs
$ curl http://localhost:3000/api/khotan/flows
$ curl http://localhost:3000/api/khotan/resources
```

If `KHOTAN_DEBUG=1` is set, you can also verify the debug surface:

```terminal
$ npx khotan plug --list
```

## 10. What agents should do next

If you are using an agent after installation:

- read the generated `AGENTS.md`
- use `/docs/agents` for the built-in skill map
- use the `.md` versions of docs pages when you want the raw, crawlable content

Continue with [Basic Usage](/docs/basic-usage) for a realistic example.