Skip to content

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_TOKEN stored 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:

chakra-convai init my-agent-app --channels phone,web_voice,web_chat

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:

chakra-convai check

2. Interactive Terminal Testing

Talk directly to your agent via audio in your terminal without dialing in or running a full server:

chakra-convai console

3. Local Development Mode

Run the worker with live code reloading:

chakra-convai dev

4. Production Worker

Run the LiveKit worker in production:

chakra-convai start


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:

docker build --secret id=fury,env=FURY_DEPLOY_TOKEN -t my-chakra-agent .