Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/samosa-ai-com--chanakya-local-friend/badge.svg)](/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

i

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)

  1. # Chanakya
  2. 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.
  3. - Chanakya Flask app on `http://127.0.0.1:5513`
  4. - AIR service on `http://127.0.0.1:5512`
  5. - Conversation layer on `http://127.0.0.1:5514`
  6. - Optional A2A bridge on `http://127.0.0.1:18770`
  7. 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.
  8. ## Quick Start
  9. ### 1. Prerequisites
  10. - Python 3.11 is the safest default for local development.
  11. - `python3.11 -m venv` available on your machine.
  12. - `uvx` available if you use the example MCP config as-is.
  13. - An OpenAI-compatible API key and base URL.
  14. ### 2. Create the virtual environment
  15. From the repo root:
  16. ```bash
  17. python3.11 -m venv .venv
  18. source .venv/bin/activate
  19. python -m pip install --upgrade pip
  20. python -m pip install -e .[dev]
  21. python -m pip install -e ./apps/AI-Router-AIR
  22. python -m pip install -e ./apps/chanakya_conversation_layer
  23. ```
  24. 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`.
  25. ### 3. Create `.env` before starting anything
  26. Start from the checked-in template:
  27. ```bash
  28. cp .env.example .env
  29. ```
  30. Then edit `.env` for your machine and credentials. Use `.env.example` as the source of truth for supported variables.
  31. 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.
  32. ### 4. Create `mcp_config_file.json` before starting anything
  33. The app expects a repo-root `mcp_config_file.json`.
  34. Start from the example:
  35. ```bash
  36. cp mcp_config_file.example.json mcp_config_file.json
  37. ```
  38. 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.
  39. ### 5. Start the stack
  40. Core stack:
  41. ```bash
  42. ./scripts/start_chanakya_air.sh core
  43. ```
  44. Core stack plus A2A components:
  45. ```bash
  46. ./scripts/start_chanakya_air.sh core+a2a
  47. ```
  48. Open the main UI at `http://127.0.0.1:5513`.
  49. ### 6. Stop the stack
  50. ```bash
  51. ./scripts/stop_chanakya_air.sh
  52. ```
  53. ## What The Startup Script Does
  54. `./scripts/start_chanakya_air.sh` starts the current local stack in this order:
  55. 1. AIR service
  56. 2. Chanakya conversation layer
  57. 3. Optional A2A services for `core+a2a`
  58. 4. Chanakya Flask app
  59. It also:
  60. - reads `.env` from the repo root unless `ENV_FILE_PATH` is already set
  61. - writes PID files and logs under `build/runtime/`
  62. - prints the service URLs after startup
  63. Use `./scripts/stop_chanakya_air.sh` to stop everything cleanly.
  64. ## Required Configuration
  65. ### `.env`
  66. Start from `.env.example` and copy it into place:
  67. ```bash
  68. cp .env.example .env
  69. ```
  70. Then edit `.env` with your local values. Replace all placeholder values marked with `<...>`:
  71. | Variable | Description | Example |
  72. |----------|-------------|---------|
  73. | `OPENAI_BASE_URL` | Your LM Studio or OpenAI-compatible server endpoint | `http://127.0.0.1:1234/v1` |
  74. | `OPENAI_API_KEY` | API key for your model server | `lm-studio` (or your key) |
  75. | `DATABASE_URL` | Path to your SQLite database | `sqlite:////home/user/chanakya_data/chanakya.db` |
  76. The defaults in `.env.example` use placeholder values and will not work out of the box.
  77. Common variables used in local development include:
  78. ```bash
  79. CHANAKYA_CORE_AGENT_BACKEND=local
  80. A2A_AGENT_URL=http://127.0.0.1:18770
  81. AIR_SERVER_PORT=5512
  82. CHANAKYA_PORT=5513
  83. CONVERSATION_LAYER_PORT=5514
  84. ```
  85. ### `mcp_config_file.json`
  86. Start from the checked-in template:
  87. ```bash
  88. cp mcp_config_file.example.json mcp_config_file.json
  89. ```
  90. This file defines the MCP servers Chanakya can connect to. The example file already includes entries for:
  91. - `mcp_websearch`
  92. - `mcp_fetch`
  93. - `mcp_calculator`
  94. - `mcp_code_execution`
  95. - `mcp_filesystem`
  96. - `mcp_git`
  97. - `mcp_http`
  98. - `mcp_json`
  99. - `mcp_shell_utils`
  100. - `mcp_weather`
  101. - `mcp_map`
  102. - `mcp_timer`
  103. - `mcp_work_tools`
  104. - `mcp_artifact_tools`
  105. If you add or remove MCP servers, restart the stack afterward so the tool loader reconnects using the updated config.
  106. ## Local Development
  107. ### Test, lint, and type-check
  108. From the repo root with the environment activated:
  109. ```bash
  110. pytest apps/chanakya/test
  111. python -m ruff check apps/chanakya/
  112. python -m mypy apps/chanakya/
  113. ```
  114. For a focused test run:
  115. ```bash
  116. pytest apps/chanakya/test/test_agent_manager.py -q
  117. ```
  118. ### Database utilities
  119. ```bash
  120. python scripts/db_viewer.py
  121. python scripts/update_database.py
  122. python scripts/clear_database.py
  123. ```
  124. Notes:
  125. - `scripts/clear_database.py` is destructive.
  126. - If `DATABASE_URL` is unset, the default SQLite database is `chanakya_data/chanakya.db`.
  127. ### Manual smoke checks
  128. These rely on external tooling and are not the default verification path:
  129. ```bash
  130. python scripts/run_maf_tools.py
  131. python scripts/test_mcp_fetch_connectivity.py --mode with-wrapper
  132. python scripts/test_mcp_fetch_connectivity.py --mode without-wrapper
  133. ```
  134. ## Runtime Files
  135. Runtime state is written under `chanakya_data/` and `build/runtime/`.
  136. - `chanakya_data/` holds application state such as the SQLite database and shared workspace data.
  137. - `build/runtime/` holds PID files and service logs from the startup scripts.
  138. If something fails to boot, check the recent logs in `build/runtime/` first.
  139. ## Service Installation On Ubuntu
  140. The repo includes a `systemd` installer for the core stack:
  141. ```bash
  142. sudo ./scripts/install-autostart-ubuntu.sh
  143. ```
  144. Important details:
  145. - it requires a repo-root `.venv`
  146. - it passes `ENV_FILE_PATH` pointing at the repo-root `.env`
  147. - it installs services for the invoking non-root user by default
  148. Useful commands:
  149. ```bash
  150. sudo systemctl status chanakya.target
  151. sudo journalctl -u chanakya-air.service -f
  152. sudo journalctl -u chanakya-conversation-layer.service -f
  153. sudo journalctl -u chanakya-app.service -f
  154. sudo systemctl restart chanakya.target
  155. ```
  156. Uninstall:
  157. ```bash
  158. sudo ./scripts/uninstall-autostart-ubuntu.sh
  159. ```
  160. ## Repository Layout
  161. This workspace contains a few related codebases. The main ones are:
  162. - `apps/chanakya/`: primary Flask app, routes, templates, core state, tests
  163. - `apps/AI-Router-AIR/`: FastAPI service used by the local stack on port 5512
  164. - `apps/chanakya_conversation_layer/`: separate conversation-layer package and tests
  165. - `scripts/`: startup, shutdown, database, and service-management scripts
  166. If you are changing runtime behavior, the most relevant files are usually:
  167. - `apps/chanakya/core/app.py`
  168. - `apps/chanakya/core/chat_service.py`
  169. - `apps/chanakya/core/store.py`
  170. - `apps/chanakya/agent/runtime.py`
  171. - `apps/chanakya/templates/`
  172. - `apps/chanakya/static/js/air_voice.js`
  173. ## Common Problems
  174. ### The stack starts but behaves incorrectly
  175. Check these first:
  176. 1. `.env` exists at the repo root and has the expected model credentials.
  177. 2. `mcp_config_file.json` exists at the repo root.
  178. 3. The virtual environment includes all three editable installs.
  179. 4. `build/runtime/*.log` shows all services stayed up after startup.
  180. ### A service starts with the wrong environment
  181. The startup scripts source the repo-root `.env` automatically. If you want a different env file, set `ENV_FILE_PATH` before invoking the script.
  182. ### MCP tools are missing
  183. Confirm that:
  184. 1. the tool exists in `mcp_config_file.json`
  185. 2. its command is installed on your machine
  186. 3. you restarted the stack after editing the MCP config
  187. ## Related Files
  188. - `mcp_config_file.example.json`: starting point for MCP server configuration
  189. - `scripts/start_chanakya_air.sh`: standard local stack entrypoint
  190. - `scripts/stop_chanakya_air.sh`: standard shutdown entrypoint
  191. - `scripts/install-autostart-ubuntu.sh`: `systemd` installer for Linux

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.