Documentation / Getting started / Companion Starter CLI
Create an application with the companion Starter CLI¶
create-vaani-app generates a consumer-owned VAANI + LiveKit application: a
Python backend and worker, a public-adapter bridge, an offline proof, and a
Next.js browser console.
The current package is privately published as create-vaani-app==0.1.2. Version
0.1.3 is in progress and is not claimed as available here. The companion is not
part of the VAANI 1.0 runtime contract.
Generate from the private package¶
uvx --from "create-vaani-app==0.1.2" create-vaani-app my-voicebot
cd my-voicebot
./scripts/setup --vaani-wheel "/path/to/vaani-1.0.0rc9-py3-none-any.whl"
./scripts/dev
Configure authentication for the approved private package index before running
uvx; do not put repository credentials in project files or commands.
setup verifies the exact RC9 wheel SHA-256 before installing it in the
generated backend, then runs an isolated provenance check. The browser console
runs at http://localhost:3000; the backend runs at
http://localhost:8000. Its offline action needs no credentials.
Generate the packaged India/Hindi preset instead with:
uvx --from "create-vaani-app==0.1.2" create-vaani-app india-voicebot \
--provider india --language hi-IN
Keep the explicit 0.1.2 pin until a later companion release is published and
approved. Do not install the in-progress 0.1.3 work as though it were released.
Run the offline proof and checks¶
./scripts/offline
uv run --directory backend --no-sync pytest
npm --prefix frontend test
npm --prefix frontend run lint
npm --prefix frontend run typecheck
npm --prefix frontend run build
Verification status¶
At the tested companion commit:
| Check | Result |
|---|---|
| Generator | 5 tests passed |
| Generated backend | 3 tests passed |
| Frontend | UI test, lint, typecheck, and Next.js 16.2.12 build passed |
Both packaged presets completed the full credential-free proof:
| Preset | Adapter path | Model path | Result |
|---|---|---|---|
Default/global en-IN |
deepgram → openrouter → smallestai |
nova-3 → openai/gpt-4.1-mini → lightning-v2 |
STT → LLM → tool → TTS; one CLOSED; zero resources |
India hi-IN |
sarvam-stt → openrouter → sarvam-tts |
saaras:v3 → openai/gpt-4.1-mini → bulbul:v2 |
STT → LLM → tool → TTS; one CLOSED; zero resources |
The India offline proof uses distinct STT/TTS scripted adapter IDs so each capability is validated independently; live configuration continues to use the supported combined Sarvam adapter.
Setup's post-install verifier runs with external Python path/home overrides
disabled and isolated import behavior. It requires both the installed
distribution and imported module to be exactly 1.0.0rc9, and requires the
module to resolve from the generated backend's .venv/site-packages. A
poisoned-PYTHONPATH regression is covered by the generator suite. The offline
result independently records 1.0.0rc9 runtime provenance.
The generated frontend uses the official LiveKit React
LiveKitRoom, RoomAudioRenderer, TrackToggle, and StartAudio components.
What the generated bridge owns¶
The worker uses LiveKit Agents AgentServer and JobContext. Generated
consumer code translates the room and audio operations into VAANI's public
LiveKitCallHandoff and LiveKitTransportAdapter.
This keeps the boundary explicit:
- core VAANI owns reusable runtime, lifecycle, adapters, and results;
- the generated app owns the high-level worker bridge and deployment wiring;
- your app still owns prompts, tools, business state, provider/model/voice/ language choices, secrets, and frontend composition.
Core VAANI intentionally does not bundle this bridge. The companion reduces setup work by generating it as editable consumer/deployment scaffolding.
Customize the generated app¶
| Concern | Generated location |
|---|---|
| Prompt | backend/src/<python_package>/prompts.py |
| Consumer tool | backend/src/<python_package>/tools.py |
| Provider, model, voice, language | vaani.app.toml and backend config |
| LiveKit bridge | backend/src/<python_package>/livekit_bridge.py |
| Browser UI | frontend/app/ |
The packaged presets are generated configuration choices, not VAANI defaults.
Live mode is not yet verified¶
The generated README exposes:
uv run --directory backend --no-sync voicebot validate-live
uv run --directory backend --no-sync voicebot worker dev
validate-live checks configuration presence. It does not contact providers or
prove a LiveKit room connection. The worker and bridge are production-shaped,
but no credentialed live connection has been tested. The starter also omits
authentication, telephony provisioning, recording, and deployment machinery.
Do not promote a generated app from offline proof alone. Complete the production readiness checklist in the target environment.
Next: customize the project structure, configure providers, or prepare for production.