.Riyaan Docs
Guides

Environment Variables Reference

1. Web App (apps/web)

Primary local file: apps/web/.env.local

Required for dashboard + demos

VariableScopeRequiredNotes
NEXT_PUBLIC_CONVEX_URLBuild-time (client)YesConvex HTTP URL (https://<deployment>.convex.site)
NEXT_PUBLIC_APP_SLUGBuild-time (client)YesDefault app slug
NEXT_PUBLIC_LIVEKIT_URLBuild-time (client)YesLiveKit websocket URL (wss://...)
NEXT_PUBLIC_GEMINI_API_KEYBuild-time (client)YesGemini key for browser chatbot/live demos
APP_SECRETRuntime (server)YesServer-only Convex app secret
LIVEKIT_URLRuntime (server)YesLiveKit API URL (https://...)
LIVEKIT_API_KEYRuntime (server)YesLiveKit API key
LIVEKIT_API_SECRETRuntime (server)YesLiveKit API secret

Used by server routes / optional flows

VariableRequiredUsed For
GEMINI_API_KEYOptional/api/summarize and /api/memory/extract (fallbacks to NEXT_PUBLIC_GEMINI_API_KEY)
LIVEKIT_SIP_TRUNK_IDOptionalPSTN/SIP outbound call demo
TWILIO_FROM_NUMBEROptionalCaller ID for outbound call flow
INTERNAL_API_TOKENRecommendedRequired by internally gated server routes (/api/twilio/call, /api/summarize, /api/memory/extract) in production. /api/session is publicly callable but rate-limited.

2. Convex Backend (apps/backend deployment env)

Set these in Convex dashboard for your deployment:

VariableRequiredNotes
GEMINI_API_KEYYesUsed for token vending, embeddings, clustering
LIVEKIT_URLYesLiveKit API URL (https://...)
LIVEKIT_API_KEYYesLiveKit credentials
LIVEKIT_API_SECRETYesLiveKit credentials

Additional backend vars:

VariableRequiredNotes
ALLOWED_ORIGINSOptionalComma-separated CORS allow-list
GOOGLE_API_KEYOptionalFallback in QA internals if GEMINI_API_KEY missing
LIVEKIT_EGRESS_MANUAL_STARTOptionalEnables explicit egress start logic
LIVEKIT_EGRESS_RECORDING_MODEOptionalroom_composite or participant_per_role
LIVEKIT_EGRESS_FILE_TYPEOptionalEffective output is mp4 in backend
LIVEKIT_EGRESS_FILEPATH_PREFIXOptionalStorage prefix for recordings
LIVEKIT_EGRESS_S3_ACCESS_KEYOptionalObject storage creds
LIVEKIT_EGRESS_S3_SECRETOptionalObject storage creds
LIVEKIT_EGRESS_S3_BUCKETOptionalObject storage bucket
LIVEKIT_EGRESS_S3_REGIONOptionalRegion (auto commonly)
LIVEKIT_EGRESS_S3_ENDPOINTOptionalS3-compatible endpoint
LIVEKIT_EGRESS_S3_FORCE_PATH_STYLEOptionalPath-style toggle
LIVEKIT_RECORDINGS_PUBLIC_BASE_URLOptionalPublic CDN/base URL for recording playback

CLI-only variable (not a dashboard env var):

VariableRequiredUsed For
CONVEX_DEPLOY_KEYYes for CLI deploy/runnpx convex deploy, npx convex run

3. SDK Agent Runtime (@riyaan/sdk/agent)

LiveKit voice agent mode

VariableRequiredNotes
GOOGLE_API_KEY or GEMINI_API_KEYYesGemini realtime + TTS/LLM paths
DEEPGRAM_API_KEYRecommendedNeeded for pipeline STT mode
LIVEKIT_URLYesAgent room connectivity
LIVEKIT_API_KEYYesLiveKit auth
LIVEKIT_API_SECRETYesLiveKit auth
CONVEX_URLOptionalBackend callbacks for persistence/persona/tools
APP_SLUGOptionalBackend auth (room slug parsing can override)
APP_SECRETOptionalBackend auth

Optional runtime tuning

VariableNotes
VOICE_NOISE_PRESETnoisy (default), balanced, or fast preset for VAD/turn/interruption tuning
PREFER_PIPELINE_FOR_ROBOT_TOOLSSet false to keep realtime first even for robot-tool rooms
SILERO_MIN_SILENCE_DURATIONNumeric tuning passed to Silero VAD loader
SILERO_ACTIVATION_THRESHOLDNumeric tuning passed to Silero VAD loader
SILERO_PREFIX_PADDING_DURATIONNumeric tuning passed to Silero VAD loader
SILERO_MIN_SPEECH_DURATIONNumeric Silero min speech duration (seconds)
DEEPGRAM_ENDPOINTING_MSDeepgram endpointing silence window in milliseconds
AGENT_MIN_INTERRUPTION_DURATION_MSLiveKit AgentSession minimum speech duration before interruption
AGENT_MIN_INTERRUPTION_WORDSLiveKit AgentSession minimum transcript words before interruption
AGENT_MIN_ENDPOINTING_DELAY_MSLiveKit AgentSession minimum endpointing delay in milliseconds
AGENT_MAX_ENDPOINTING_DELAY_MSLiveKit AgentSession maximum endpointing delay in milliseconds
REALTIME_VAD_START_SENSITIVITYGemini Live realtime VAD start sensitivity (LOW/HIGH)
REALTIME_VAD_END_SENSITIVITYGemini Live realtime VAD end sensitivity (LOW/HIGH)
REALTIME_VAD_PREFIX_PADDING_MSGemini Live realtime VAD prefix padding in milliseconds
REALTIME_VAD_SILENCE_DURATION_MSGemini Live realtime VAD silence duration in milliseconds
REALTIME_ACTIVITY_HANDLINGGemini Live activity handling (NO_INTERRUPTION or START_OF_ACTIVITY_INTERRUPTS)
LIVEKIT_NOISE_CANCELLATION_MODULE_IDOptional LiveKit noise cancellation module id for server-side input filtering
LIVEKIT_NOISE_CANCELLATION_OPTIONS_JSONJSON object string passed as module options for the LiveKit noise cancellation module

Pi runtime provider keys (when using createAgent)

VariableRequiredNotes
ANTHROPIC_API_KEYOptionalRequired only for Anthropic provider usage
OPENAI_API_KEYOptionalRequired only for OpenAI provider usage
GOOGLE_API_KEY / GEMINI_API_KEYOptionalRequired for Google provider usage

4. Optional Telephony Adapter Env Vars

Used if your app wires env directly into @riyaan/sdk/telephony adapters:

VariableProvider
TWILIO_ACCOUNT_SIDTwilio
TWILIO_AUTH_TOKENTwilio
TWILIO_FROM_NUMBERTwilio
TELNYX_API_KEYTelnyx
TELNYX_CONNECTION_IDTelnyx

5. E2E / Playwright

VariableNotes
BASE_URLPlaywright base URL (default http://localhost:3200)
CIAffects Playwright server reuse behavior
E2E_INTEGRATIONEnables integration-spec paths
E2E_TWILIO_ALLOW_CALLSAllows real PSTN test call execution
E2E_TWILIO_TODestination number for Twilio call integration tests

6. Backend Smoke Test (scripts/backend-smoke-test.mjs)

VariableRequiredNotes
SMOKE_BASE_URLYesConvex deployment HTTP URL, e.g. https://<deployment>.convex.site
SMOKE_APP_SLUGYesApp slug used for auth/session and flow checks
SMOKE_APP_SECRETYesApp secret used to mint session token
SMOKE_TIMEOUT_MSOptionalPer-request timeout in milliseconds (default 30000)

Script fallbacks:

  • SMOKE_BASE_URL can fall back to CONVEX_HTTP_URL, NEXT_PUBLIC_CONVEX_URL, or CONVEX_URL.
  • SMOKE_APP_SLUG can fall back to NEXT_PUBLIC_APP_SLUG or APP_SLUG.
  • SMOKE_APP_SECRET can fall back to APP_SECRET.

Common Pitfalls

Build-time variables

NEXT_PUBLIC_* vars are build-time in Next.js. Changing them requires rebuild/redeploy.

Secret exposure

Keep APP_SECRET server-only. Never expose it through NEXT_PUBLIC_*.

URL protocols

Use wss:// for NEXT_PUBLIC_LIVEKIT_URL and https:// for LIVEKIT_URL.

Voice agent fallback

For full voice-agent fallback behavior, set DEEPGRAM_API_KEY in agent environments.

Edit on GitHub

Last updated on

Knowledge Base

Hybrid search with vector embeddings, BM25, and transcript memory fusion.

API Reference

Complete HTTP API reference for the Riyaan platform — 79 endpoints across 23 categories.

On this page

Environment Variables Reference1. Web App (apps/web)Required for dashboard + demosUsed by server routes / optional flows2. Convex Backend (apps/backend deployment env)3. SDK Agent Runtime (@riyaan/sdk/agent)LiveKit voice agent modeOptional runtime tuningPi runtime provider keys (when using createAgent)4. Optional Telephony Adapter Env Vars5. E2E / Playwright6. Backend Smoke Test (scripts/backend-smoke-test.mjs)Common Pitfalls