Configuration Reference
The main configuration file for every application built on the engine is chakra.toml.
Editor Autocompletion & Schema Validation
If you use VS Code (with the Even Better TOML extension), add this line at the top of chakra.toml for autocomplete and validation:
chakra.toml Reference
[app]
Global application properties:
[app]
name = "my-agent"
skills = "my_agent.skills"
hooks = "my_agent.hooks"
default_language = "si"
supported_languages = ["si", "ta", "en"]
timezone = "Asia/Colombo"
config_dir = "config"
num_idle_processes = 2
[[agents]]
Declares agents, their respective channels, and language bindings:
[[agents]]
name = "ivr_sinhala"
channel = "phone"
language = "si"
[[agents]]
name = "web_assistant"
channel = "web"
[web]
Settings for web voice, video, and chat channels:
[web]
# Number of camera frames captured per user turn (1 frame/sec)
vision_frames = 4
# Enable vision frames on managed chakra pipeline
chakra_vision = true
# Gemini model for chat sessions on gemini_live licences
chat_model = "gemini-2.5-flash"
# Idle chat disconnect timeout in seconds
chat_idle_timeout_seconds = 600
# Preserve language selection throughout the web session
keep_language = true
[pipeline]
Pipeline selection fallback:
[greeting]
Configures introductory lines spoken upon user connect:
[greeting]
first = "greetings.first_time"
returning_template = "greetings.returning"
returning_shape = "returning_caller"
delay_seconds = 0.5
[features]
Enables optional engine subsystems:
[features]
database = true # Connects to PostgreSQL for caller memory & analytics
transcripts = true # Writes call turn transcripts to DB
memory_fallback = true # Generates memory summary if caller hangs up abruptly
[tools]
Registers built-in engine tools:
[tools]
builtin = [
"end_call",
"save_caller_memory",
"capture_feedback",
"query_knowledge_base"
]
wait_line = "languages.{lang}.prompts.tool_wait"
wait_line (Chakra Voice pipeline, optional): a short line the agent says
the moment it starts a tool (a knowledge-base search, the weather, a price),
so the caller is not left in silence while the answer is looked up. A dotted
path into config/instructions.json; with a list of lines, one is picked at random each time, never the same twice running. Write
it in the call's language, at least about 20 characters (Chakra TTS mumbles
very short pieces), for example "හරි, මම ඒ ගැන ටිකක් හොයලා බලන්නම්.". It is
recorded once in the call's voice and played from that recording; it is not
said for wait_line_skip tools (default end_call, save_caller_memory,
capture_feedback), nor when the model has already said something that turn.
[silence]
Dictates user silence handling:
[silence]
mode = "monitor" # "monitor" (turn pipeline), "away" (Gemini Live), or "off"
timeout_seconds = 7.0
prompts = ["silence.check_in_1", "silence.check_in_2"]
goodbye = "silence.disconnect"
[call] & [call_limit]
Call duration safety constraints and daily talk quotas:
[call]
max_duration_seconds = 900
caller_join_timeout_seconds = 20.0
max_duration_goodbye = "call.max_duration_reached"
[call_limit]
limit_reached = "limits.daily_limit_reached"
approaching_limit = "limits.warning"
time_up = "limits.goodbye"
min_usable_seconds = 30
[rag] (Knowledge Base)
Vector retrieval configuration:
Environment Variables (.env)
| Variable | Description | Required |
|---|---|---|
CHAKRA_LICENSE_KEY |
Your cryptographic Chakra Console license key | Yes |
LIVEKIT_URL |
LiveKit server WebSocket endpoint | Yes |
LIVEKIT_API_KEY |
LiveKit project API key | Yes |
LIVEKIT_API_SECRET |
LiveKit project API secret | Yes |
GOOGLE_API_KEY |
Required for Gemini Live or RAG embedding creation | Optional |
DATABASE_URL |
PostgreSQL connection string for caller memory and analytics | Optional |
CHAKRA_PIPELINE |
Override default pipeline selection (chakra or gemini_live) |
Optional |
APP_PORT |
Port for the HTTP health / admin worker | Optional |
LANGFUSE_* |
Tracing & observability credentials | Optional |