Getting Started
Requirements
- Python:
3.12(x86_64 POSIX Linux for production deployment; macOS/Linux/WSL for local dev) - License: Active Chakra Console License Key (
CHAKRA_LICENSE_KEY) - LiveKit Server: Self-hosted or LiveKit Cloud URL & API credentials
Installation
chakra-convai is distributed as a compiled, licensed wheel on Chakra Labs' private package index (pypi.chakralabsai.com, login deploy with the install token Chakra Labs gives you):
pip install chakra-convai --extra-index-url "https://deploy:${FURY_DEPLOY_TOKEN}@pypi.chakralabsai.com/simple/"
Security Note: Keep your
FURY_DEPLOY_TOKENstored in CI/CD secrets or local environment files. Never commit credentials to source control.
Scaffolding a New Application: chakra-convai init
The quickest way to bootstrap a new application is with the CLI scaffolding command:
If --channels is omitted and CHAKRA_LICENSE_KEY is present in your environment, the CLI queries Chakra Console to discover your project's allowed channels automatically.
Generated Project Structure
my-agent-app/
├── chakra.toml # Application configuration & agents
├── config/
│ └── instructions.json # Prompts, spoken lines, guardrails
├── my_agent_app/
│ ├── __init__.py
│ ├── hooks.py # Optional lifecycle hooks
│ └── skills/
│ └── demo/
│ ├── __init__.py
│ └── tool.py # Sample tool / skill implementation
├── main.py # Application entrypoint
├── Dockerfile # Production container build
├── .env.example # Secrets template
└── README.md # Integration guide & session payload docs
Configuration and Secrets
Copy .env.example to .env and supply your keys:
CHAKRA_LICENSE_KEY="your-chakra-license-key"
LIVEKIT_URL="wss://your-project.livekit.cloud"
LIVEKIT_API_KEY="your-livekit-api-key"
LIVEKIT_API_SECRET="your-livekit-api-secret"
# Required only if using gemini_live pipeline or knowledge-base embeddings
GOOGLE_API_KEY="your-google-api-key"
# Optional database for caller memory, daily limits & analytics
DATABASE_URL="postgresql://user:password@localhost:5432/ivr_db"
Running the Application
chakra-convai provides built-in commands for every stage of development:
1. Verify Configuration & License
Check that all prompts, tools, pipelines, and license permissions are valid:
2. Interactive Terminal Testing
Talk directly to your agent via audio in your terminal without dialing in or running a full server:
3. Local Development Mode
Run the worker with live code reloading:
4. Production Worker
Run the LiveKit worker in production:
Production Docker Deployment
A complete production Dockerfile requires Python 3.12 and build tools for any native dependencies:
# syntax=docker/dockerfile:1
FROM python:3.12-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential curl && \
rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN --mount=type=secret,id=fury,env=FURY_DEPLOY_TOKEN \
pip install --no-cache-dir -r requirements.txt \
--extra-index-url "https://deploy:${FURY_DEPLOY_TOKEN}@pypi.chakralabsai.com/simple/"
COPY . .
CMD ["chakra-convai", "start"]
Build with buildkit secrets: