A self-hosted AI assistant runtime. Define your tools, connect your services, and interact through an HTTP API or CLI -- all from a single YAML file.
Ronnyx runs as a persistent service with session memory and automatic tool dispatch. It supports both external tool servers (via MCP) and custom Python functions, so you can mix off-the-shelf integrations with your own logic.
- Connect external tool servers or write your own Python tools
- Session-aware chat API with multi-turn conversation history
- Single YAML config with environment variable resolution
- Built-in CLI client for interactive use
- Async LangGraph agent with automatic tool routing
pip install ronnyxCreate a ronnyx.yaml in the directory you will run Ronnyx from:
llm:
model: gpt-4o
api_key: ${OPENAI_API_KEY}
servers:
github:
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_TOKEN: ${GITHUB_TOKEN}A fully commented version is in ronnyx.yaml.example.
Set your API keys in a .env file next to it, or directly in ronnyx.yaml:
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
Start the server:
ronnyx-serveIn a separate terminal, start the CLI:
ronnyx-chatronnyx-serve listens on 127.0.0.1:8000 by default. Use --host and --port to change it:
ronnyx-serve --port 9000
ronnyx-serve --host 0.0.0.0 # reachable from other machinesThe API has no authentication, and the agent acts with every credential in your config. Anyone who can reach the port can use those tools. Keep the default 127.0.0.1 unless the server sits behind a reverse proxy or private network that controls access.
All configuration lives in ronnyx.yaml. Environment variables referenced with ${VAR} are resolved from the shell environment or a .env file.
llm:
model: gpt-4o
api_key: ${OPENAI_API_KEY}
context:
github_username: ${GITHUB_USERNAME}
servers:
github:
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_TOKEN: ${GITHUB_TOKEN}
custom_tools:
- function: my_tools.list_repos
name: list_repos
description: "List GitHub repos for a user with sorting"llm -- Model, API key, and optional base_url for an OpenAI-compatible
provider. Omit base_url to keep the default endpoint behavior. For a local
Ollama server, use its OpenAI-compatible endpoint and a placeholder key (Ronnyx
requires a non-empty key even when the server does not authenticate it):
llm:
model: llama3.1
api_key: ollama
base_url: http://localhost:11434/v1Other providers can use their own endpoint URL and API key. Like other config
values, base_url supports ${VAR} environment variable references.
context -- Key-value pairs injected into the system prompt. Use this to give the assistant information it cannot retrieve from tools (username, timezone, preferences).
servers -- External tool servers using the Model Context Protocol. Each entry spawns a subprocess (stdio) or connects to a remote endpoint (SSE). All tools exposed by the server become available to the agent automatically.
custom_tools -- Python functions loaded alongside server tools. Point to any callable or StructuredTool instance using its dotted import path. Use this when you need custom logic or when an external server doesn't cover your use case.
knowledge -- Optional knowledge base over your own documents. See Knowledge Base.
Ronnyx can answer questions from your own documents using GraphRAG. This is optional and requires Python 3.11+.
pip install "ronnyx[graphrag]"Enable it in ronnyx.yaml:
knowledge:
provider: graphrag
root: ./knowledgeCreate the project, add your documents, and build the index:
ronnyx-index --init # creates knowledge/ with GraphRAG settings
# put .txt files in knowledge/input/
ronnyx-index # builds the indexIndexing calls the LLM for every chunk of every document, so it can be expensive on large collections. The command asks for confirmation first; pass --yes to skip it. GraphRAG settings, including models, live in knowledge/settings.yaml. The Ronnyx API key is used unless GRAPHRAG_API_KEY is set.
After indexing, restart ronnyx-serve. The agent gets two tools:
knowledge_local_search-- specific questions about people, projects, or concepts in your documentsknowledge_global_search-- broad questions such as main themes or overall summaries
If the index is missing or GraphRAG is not installed, the server still starts and logs a warning.
Send a message and receive a response within a session.
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{"session_id": "1", "message": "How many open issues do I have?"}'{
"session_id": "1",
"reply": "You have 3 open issues in your repository."
}Each session maintains its own conversation history, so follow-up questions work naturally.
List all loaded tools.
curl http://localhost:8000/api/toolsHealth check.
The CLI connects to the running server over HTTP.
ronnyx-chat
ronnyx-chat --base-url http://localhost:8000/api/chat --session-id 42You > How many open issues do I have?
Ronnyx > You have 3 open issues in your repository.
The server must be running before starting the CLI.
git clone https://github.com/baranylcn/ronnyx
cd ronnyx
python -m venv venv
source venv/bin/activate # macOS / Linux
venv\Scripts\activate # Windows
pip install -e ".[dev]"
cp ronnyx.yaml.example ronnyx.yamlRun the tests:
pytest -qAll tests run offline without API keys or external servers.
Contributions are welcome. See CONTRIBUTING.md for guidelines. Pull requests should be focused, clearly scoped, and include tests.
MIT. See LICENSE.md.