Quantum Hermes Free Router Kit: model tool for Hermes Agent

Starter kit that routes Hermes Agent through a local LiteLLM proxy with free-tier models and fallback

What Quantum Hermes Free Router Kit does

Quantum Hermes Free Router Kit collects scripts, templates and documentation for running a LiteLLM proxy at 127.0.0.1:4000/v1 and registering it in ~/.hermes/config.yaml as an OpenAI-compatible custom provider named quantum_litellm. Hermes then sends its model requests to the proxy, which routes them to free or free-tier APIs such as Gemini, OpenCode and Kilocode. The README stresses that LiteLLM is the only routing layer and there is no separate router in between.

The kit supports several keys for the same provider to stay within rate limits, and automatic failover when a provider or key is exhausted. It includes an install script, a doctor.sh diagnosis script, systemd service templates for Linux including WSL2, and scripts that audit for accidentally committed secrets. A reliability note covers Telegram long tasks that show waiting-for-stream errors, and recommends turning streaming off in the Hermes config. Docs cover architecture, configuration, routing and troubleshooting.

Key features

Local LiteLLM proxy registered in Hermes as the quantum_litellm custom provider
Load balancing across several keys for the same free-tier provider
Automatic failover when a provider or key is exhausted
systemd service templates, including for WSL2
doctor.sh diagnosis script and secret-audit scripts
Documented fix for Telegram stream errors by disabling streaming

When to use it

Running Hermes Agent on free-tier model APIs without paying per token
Rotating between several API keys to stay under rate limits
Keeping a local model router running as a background service on a Linux or WSL2 machine

Who it is for: Hermes Agent users who want a local, self-hosted router over free and free-tier model providers.

How it fits with Hermes Agent

Built for Hermes Agent, which is configured to use the LiteLLM proxy as a custom provider; the README states it is not an official Hermes Agent or LiteLLM project.

How to install Quantum Hermes Free Router Kit

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

git clone https://github.com/spacepirate15/quantum-hermes-free-router-kit.git
cd quantum-hermes-free-router-kit
bash scripts/install.sh
nano .env

Requirements: Free or free-tier provider API keys you own, on Ubuntu, WSL2 or macOS

Note: It is an unofficial community kit, and the free-tier providers it routes to keep their own quotas and terms.

FAQ

What is Quantum Hermes Free Router Kit?

Quantum Hermes Free Router Kit is a set of scripts, templates and docs for running a local LiteLLM proxy in front of free-tier model APIs. Hermes Agent connects to it as a custom provider.

Does Quantum Hermes Free Router Kit work with Hermes Agent?

Yes, it is made for Hermes Agent. You register the quantum_litellm provider in ~/.hermes/config.yaml, as described in docs/HERMES_INTEGRATION.md.

How do I install Quantum Hermes Free Router Kit?

Clone the repository, run bash scripts/install.sh, and add your API keys to .env. Then run bash scripts/doctor.sh to check the setup and start the proxy with .venv/bin/litellm --config config.yaml --port 4000.