Quickstart

This guide walks you through the full setup: creating an app, connecting a voice agent, and viewing the conversation in the dashboard.

Prerequisites

Node.js 20+
A Convex deployment (the backend)
LiveKit project credentials
Gemini API key

Understand the data model

Before setting anything up, understand that everything in Riyaan revolves around an App. An app is one configured voice agent with its own identity, tools, guardrails, and knowledge base. See Architecture for the full picture.

Seed your app

Seeding writes your app's configuration into Convex. You can seed a pre-built demo scenario or create a blank app.

Demo scenarios come with tools, guardrails, knowledge docs, and sample state pre-configured.

Terminal

cd apps/backend
npx convex run seedScenarios:seedScenarioBySlug \
  '{"secret":"your-app-secret","slug":"demo-dentist"}' --prod

Available demo slugs: demo-dentist, demo-earnings, demo-ecommerce, demo-facility-management, demo-sales, demo-onboarding, baby-alpha, alpha-mini-hardtech, cruzr-translator.

Terminal

cd apps/backend
npx convex run seed:seedApp '{
  "slug": "my-app",
  "name": "My App",
  "secret": "your-app-secret",
  "modelId": "gemini-2.5-flash-native-audio-preview-12-2025",
  "replyAsAudio": true,
  "systemPrompt": "You are a helpful assistant."
}'

The secret you pass here becomes the APP_SECRET you'll use in your web app's environment.

Configure environment variables

Set these in your web app's .env.local:

apps/web/.env.local

NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.site
NEXT_PUBLIC_APP_SLUG=my-app
APP_SECRET=your-app-secret

NEXT_PUBLIC_LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_URL=https://your-project.livekit.cloud
LIVEKIT_API_KEY=...
LIVEKIT_API_SECRET=...

NEXT_PUBLIC_GEMINI_API_KEY=...

See Environment Variables for the complete reference.

Create a session

Your server route calls Convex to get a browser-safe session token:

Terminal

curl -X POST https://your-deployment.convex.site/api/auth/session \
  -H 'Content-Type: application/json' \
  -d '{"appSlug": "my-app", "appSecret": "your-app-secret"}'

Response:

{ "sessionToken": "abc-123-...", "expiresAt": 1709654400000 }

Connect a voice agent

Via LiveKit (recommended)

Create a room and join it with the LiveKit client SDK:

Terminal

curl -X POST https://your-deployment.convex.site/api/livekit/rooms \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SESSION_TOKEN' \
  -d '{"sessionId": "my-session-123"}'

The agent process picks up the room automatically, loads your app's config (system prompt, persona, tools), and starts listening.

Via browser chatbot

Use the SDK's ChatBot component for a text/voice chat directly in the browser:

import { ChatBot } from '@riyaan/sdk/chatbot';

<ChatBot
  apiKey={process.env.NEXT_PUBLIC_GEMINI_API_KEY!}
  config={{
    systemPrompt: 'You are a helpful assistant.',
    modelId: 'gemini-2.5-flash-native-audio-preview-12-2025',
    replyAsAudio: true,
  }}
/>

Add tools

Terminal

curl -X POST https://your-deployment.convex.site/api/tools \
  -H 'Authorization: Bearer SESSION_TOKEN' \
  -d '{
    "name": "check_order_status",
    "description": "Look up the status of a customer order",
    "parametersSchema": "{\"type\":\"object\",\"properties\":{\"orderId\":{\"type\":\"string\"}},\"required\":[\"orderId\"]}"
  }'

Or include tools in your seed data for automatic setup. See Tools.

Add guardrails

Define safety rules that filter every message:

Terminal

curl -X POST https://your-deployment.convex.site/api/guardrails/rules \
  -H 'Authorization: Bearer SESSION_TOKEN' \
  -d '{
    "type": "topic",
    "pattern": "medical advice|legal advice",
    "action": "block",
    "userMessage": "I cannot provide medical or legal advice."
  }'

See Guardrails.

View in the dashboard

Open the dashboard to see conversations, tool executions, guardrail violations, and analytics in real time.

pnpm dev
# Open http://localhost:3200

Next steps

Architecture — Understand how apps, tools, auth, and deployment connect.
Knowledge Base — Add RAG documents for your agent.
API Reference — Full endpoint documentation.

On this page