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.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/samosa-ai-com--chanakya-local-friend)HTML
<a href="/listings/samosa-ai-com--chanakya-local-friend"><img src="/api/listings/samosa-ai-com--chanakya-local-friend/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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 was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 282 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- ./scripts/start_chanakya_air.sh core
- ```
- Core stack plus A2A components:
- ```bash
- ./scripts/start_chanakya_air.sh core+a2a
- ```
- Open the main UI at `http://127.0.0.1:5513`.
- ### 6. Stop the stack
- ```bash
- ./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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- pytest apps/chanakya/test
- python -m ruff check apps/chanakya/
- python -m mypy apps/chanakya/
- ```
- For a focused test run:
- ```bash
- pytest apps/chanakya/test/test_agent_manager.py -q
- ```
- ### Database utilities
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.