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 venv available on your machine.
• uvx available 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:

1. AIR service
2. Chanakya conversation layer
3. Optional A2A services for core+a2a
4. Chanakya Flask app

It also:

• reads .env from the repo root unless ENV_FILE_PATH is 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_websearch
• mcp_fetch
• mcp_calculator
• mcp_code_execution
• mcp_filesystem
• mcp_git
• mcp_http
• mcp_json
• mcp_shell_utils
• mcp_weather
• mcp_map
• mcp_timer
• mcp_work_tools
• mcp_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.py is destructive.
• If DATABASE_URL is unset, the default SQLite database is chanakya_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_PATH pointing 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, tests
• apps/AI-Router-AIR/: FastAPI service used by the local stack on port 5512
• apps/chanakya_conversation_layer/: separate conversation-layer package and tests
• scripts/: startup, shutdown, database, and service-management scripts

If you are changing runtime behavior, the most relevant files are usually:

• apps/chanakya/core/app.py
• apps/chanakya/core/chat_service.py
• apps/chanakya/core/store.py
• apps/chanakya/agent/runtime.py
• apps/chanakya/templates/
• apps/chanakya/static/js/air_voice.js

Common Problems

The stack starts but behaves incorrectly

Check these first:

1. .env exists at the repo root and has the expected model credentials.
2. mcp_config_file.json exists at the repo root.
3. The virtual environment includes all three editable installs.
4. build/runtime/*.log shows 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:

1. the tool exists in mcp_config_file.json
2. its command is installed on your machine
3. you restarted the stack after editing the MCP config

Related Files

• mcp_config_file.example.json: starting point for MCP server configuration
• scripts/start_chanakya_air.sh: standard local stack entrypoint
• scripts/stop_chanakya_air.sh: standard shutdown entrypoint
• scripts/install-autostart-ubuntu.sh: systemd installer for Linux