Ronnyx
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.
Features
- 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
Quick Start
pip install ronnyx
Create 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-serve
In a separate terminal, start the CLI:
ronnyx-chat
Running the Server
ronnyx-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 machines
The 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.
Configuration
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"
Sections
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/v1
Other 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.
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: ./knowledge
Create 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 index
Indexing 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.
API
POST /api/chat
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.
GET /api/tools
List all loaded tools.
curl http://localhost:8000/api/tools
GET /
Health check.
CLI
The CLI connects to the running server over HTTP.
ronnyx-chat
ronnyx-chat --base-url http://localhost:8000/api/chat --session-id 42
You > 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.
Development
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.yaml
Run the tests:
pytest -q
All tests run offline without API keys or external servers.
Contributing
Contributions are welcome. See CONTRIBUTING.md for guidelines. Pull requests should be focused, clearly scoped, and include tests.
License
MIT. See LICENSE.md.
Metadata
Release files for ronnyx 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ronnyx-0.2.0.tar.gz | 13.0 kB | With provenance | Details for ronnyx-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ronnyx-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for ronnyx-0.2.0-py3-none-any.whl |
Total release size: 29.4 kB
Release files / ronnyx-0.2.0.tar.gz
| Download URL | ronnyx-0.2.0.tar.gz |
|---|---|
| Size | 13.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
642b5a1dc0a6520f9acb088d5977501d81061a7ae50a55d8372c85335f51456b
|
|
BLAKE2b-256 checksum How to use checksums |
dcec35f7cfbc0839c586fef580ba238b1ab570867dbf8e3fb813d9475a693077
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / ronnyx-0.2.0-py3-none-any.whl
| Download URL | ronnyx-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d582c9ccbc0f0024aa1e60a88cc93972637d3982fe559dc904ecba179e0bc0ab
|
|
BLAKE2b-256 checksum How to use checksums |
35fc75eec96daea488218f3d66ba1d0204150b064da31b35ec4183c044a62022
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for ronnyx 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ronnyx-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.