Skip to main content

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 documents
  • knowledge_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)

Source distribution for ronnyx 0.2.0
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)

Table of built distributions (wheels) for ronnyx 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page