Installation

Install 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

1. Install the package

$ npm i khotan-data

2. Set environment variables

KHOTAN_SECRET=your-secret-here...
KHOTAN_URL=http://localhost:3000
KHOTAN_WEBHOOK_URL=https://abc123.ngrok.app   # tunnel for inbound webhooks

KHOTAN_SECRET=...
KHOTAN_URL=https://myapp.vercel.app
KHOTAN_WEBHOOK_URL=https://myapp.vercel.app

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

3. Initialize khotan and install built-in skills

$ npx khotan init --yes

This scaffolds the core runtime and auto-accepts the prompt to install khotan's built-in agent 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

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

• khotan_plugs
• khotan_resources
• khotan_flows
• khotan_wires
• khotan_webhook_handlers
• khotan_webhook_events
• khotan_runs
• khotan_mappings

5. Run migrations

$ npx khotan migrate

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

6. Add the first components

$ 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

$ npx khotan add config-page-1

This creates a /config page that renders the Hub.

$ 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:

{
  "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

$ 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:

$ npx khotan plug --list

10. What agents should do next

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