Chanakya Local Friend
Chanakya is an advanced, open-source, and self-hostable voice assistant designed for privacy, power, and flexibility. It leverages local AI/ML models to ensure your data stays with you. It Integrates with 1000+ third-party MCP servers including Home Assistant.
Ask AI about Chanakya Local Friend
Powered by Claude · Grounded in docs
I know everything about Chanakya Local Friend. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Chanakya
Chanakya is an advanced, open-source, and self-hostable voice assistant designed for privacy, power, and flexibility. It can leverage local AI/ML models to help keep data under your control and supports connecting to third-party MCP servers through configuration. A network of intelligent agents collaborates to complete tasks, provide insights, and maintain ongoing workflows.
- Chanakya Flask app on
http://127.0.0.1:5513 - AIR service on
http://127.0.0.1:5512 - Conversation layer on
http://127.0.0.1:5514 - Optional A2A bridge on
http://127.0.0.1:18770
The most important setup rule is simple: create the repo-root .env and mcp_config_file.json before starting the stack. The startup scripts read those files immediately.
Quick Start
1. Prerequisites
- Python 3.11 is the safest default for local development.
python3.11 -m venvavailable on your machine.uvxavailable if you use the example MCP config as-is.- An OpenAI-compatible API key and base URL.
2. Create the virtual environment
From the repo root:
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .[dev]
python -m pip install -e ./apps/AI-Router-AIR
python -m pip install -e ./apps/chanakya_conversation_layer
If you prefer conda for day-to-day development, that is still fine. The only hard requirement is that the systemd installer expects a repo-root .venv.
3. Create .env before starting anything
Start from the checked-in template:
cp .env.example .env
Then edit .env for your machine and credentials. Use .env.example as the source of truth for supported variables.
The startup scripts source this file automatically and export ENV_FILE_PATH for child processes. If this file is missing, the services start without your intended runtime configuration.
4. Create mcp_config_file.json before starting anything
The app expects a repo-root mcp_config_file.json.
Start from the example:
cp mcp_config_file.example.json mcp_config_file.json
Then edit it for your environment if needed. Use mcp_config_file.example.json as the source of truth for the default MCP server layout. The checked-in example includes both local Python-backed MCP servers and uvx-launched servers.
5. Start the stack
Core stack:
./scripts/start_chanakya_air.sh core
Core stack plus A2A components:
./scripts/start_chanakya_air.sh core+a2a
Open the main UI at http://127.0.0.1:5513.
6. Stop the stack
./scripts/stop_chanakya_air.sh
What The Startup Script Does
./scripts/start_chanakya_air.sh starts the current local stack in this order:
- AIR service
- Chanakya conversation layer
- Optional A2A services for
core+a2a - Chanakya Flask app
It also:
- reads
.envfrom the repo root unlessENV_FILE_PATHis already set - writes PID files and logs under
build/runtime/ - prints the service URLs after startup
Use ./scripts/stop_chanakya_air.sh to stop everything cleanly.
Required Configuration
.env
Start from .env.example and copy it into place:
cp .env.example .env
Then edit .env with your local values. Replace all placeholder values marked with <...>:
| Variable | Description | Example |
|---|---|---|
OPENAI_BASE_URL | Your LM Studio or OpenAI-compatible server endpoint | http://127.0.0.1:1234/v1 |
OPENAI_API_KEY | API key for your model server | lm-studio (or your key) |
DATABASE_URL | Path to your SQLite database | sqlite:////home/user/chanakya_data/chanakya.db |
The defaults in .env.example use placeholder values and will not work out of the box.
Common variables used in local development include:
CHANAKYA_CORE_AGENT_BACKEND=local
A2A_AGENT_URL=http://127.0.0.1:18770
AIR_SERVER_PORT=5512
CHANAKYA_PORT=5513
CONVERSATION_LAYER_PORT=5514
mcp_config_file.json
Start from the checked-in template:
cp mcp_config_file.example.json mcp_config_file.json
This file defines the MCP servers Chanakya can connect to. The example file already includes entries for:
mcp_websearchmcp_fetchmcp_calculatormcp_code_executionmcp_filesystemmcp_gitmcp_httpmcp_jsonmcp_shell_utilsmcp_weathermcp_mapmcp_timermcp_work_toolsmcp_artifact_tools
If you add or remove MCP servers, restart the stack afterward so the tool loader reconnects using the updated config.
Local Development
Test, lint, and type-check
From the repo root with the environment activated:
pytest apps/chanakya/test
python -m ruff check apps/chanakya/
python -m mypy apps/chanakya/
For a focused test run:
pytest apps/chanakya/test/test_agent_manager.py -q
Database utilities
python scripts/db_viewer.py
python scripts/update_database.py
python scripts/clear_database.py
Notes:
scripts/clear_database.pyis destructive.- If
DATABASE_URLis unset, the default SQLite database ischanakya_data/chanakya.db.
Manual smoke checks
These rely on external tooling and are not the default verification path:
python scripts/run_maf_tools.py
python scripts/test_mcp_fetch_connectivity.py --mode with-wrapper
python scripts/test_mcp_fetch_connectivity.py --mode without-wrapper
Runtime Files
Runtime state is written under chanakya_data/ and build/runtime/.
chanakya_data/holds application state such as the SQLite database and shared workspace data.build/runtime/holds PID files and service logs from the startup scripts.
If something fails to boot, check the recent logs in build/runtime/ first.
Service Installation On Ubuntu
The repo includes a systemd installer for the core stack:
sudo ./scripts/install-autostart-ubuntu.sh
Important details:
- it requires a repo-root
.venv - it passes
ENV_FILE_PATHpointing at the repo-root.env - it installs services for the invoking non-root user by default
Useful commands:
sudo systemctl status chanakya.target
sudo journalctl -u chanakya-air.service -f
sudo journalctl -u chanakya-conversation-layer.service -f
sudo journalctl -u chanakya-app.service -f
sudo systemctl restart chanakya.target
Uninstall:
sudo ./scripts/uninstall-autostart-ubuntu.sh
Repository Layout
This workspace contains a few related codebases. The main ones are:
apps/chanakya/: primary Flask app, routes, templates, core state, testsapps/AI-Router-AIR/: FastAPI service used by the local stack on port 5512apps/chanakya_conversation_layer/: separate conversation-layer package and testsscripts/: startup, shutdown, database, and service-management scripts
If you are changing runtime behavior, the most relevant files are usually:
apps/chanakya/core/app.pyapps/chanakya/core/chat_service.pyapps/chanakya/core/store.pyapps/chanakya/agent/runtime.pyapps/chanakya/templates/apps/chanakya/static/js/air_voice.js
Common Problems
The stack starts but behaves incorrectly
Check these first:
.envexists at the repo root and has the expected model credentials.mcp_config_file.jsonexists at the repo root.- The virtual environment includes all three editable installs.
build/runtime/*.logshows all services stayed up after startup.
A service starts with the wrong environment
The startup scripts source the repo-root .env automatically. If you want a different env file, set ENV_FILE_PATH before invoking the script.
MCP tools are missing
Confirm that:
- the tool exists in
mcp_config_file.json - its command is installed on your machine
- you restarted the stack after editing the MCP config
Related Files
mcp_config_file.example.json: starting point for MCP server configurationscripts/start_chanakya_air.sh: standard local stack entrypointscripts/stop_chanakya_air.sh: standard shutdown entrypointscripts/install-autostart-ubuntu.sh:systemdinstaller for Linux
