llm-keypool: model tool for Hermes Agent

Free-tier LLM API key pool with rotation, 429 cooldowns and a local OpenAI-compatible proxy

What llm-keypool does

Users register API keys from providers such as Groq, Cerebras, Mistral, OpenRouter, SambaNova and Google once. llm-keypool then round-robins across them, rotating every five requests by default. When a key hits a 429 rate limit it enters cooldown and the next call retries with a different key. Each key can be tagged with capabilities including agentic, fast, general_purpose, code, vision and large_context, and each proxy instance filters keys by the capabilities it serves.

The llm-keypool proxy command starts a local server at http://localhost:8000/v1 that any OpenAI-compatible tool can use. For Hermes Agent, the README describes two proxy instances: port 8000 for the main agentic loop and port 8001 for fast delegate calls. State lives in SQLite at ~/.llm-keypool/keys.db, so rotation position and cooldowns survive restarts. An audit log records provider, model, token counts and latency for each call, attributed through an X-Subscriber-ID header. Interfaces include a CLI, a Textual TUI and a LangChain drop-in.

Key features

Round-robin rotation across keys from several providers, every 5 requests by default
Automatic 429 cooldown with retry on a different key
Capability tags that route agentic and fast traffic to separate proxy instances
OpenAI-compatible local proxy at http://localhost:8000/v1
Audit log of provider, model, token counts and latency per call
CLI, Textual TUI and a LangChain drop-in called AggregatorChat

When to use it

Running Hermes Agent on free-tier keys with no paid API subscription
Splitting main-loop and delegated sub-agent calls across two proxy ports
Tracking which agent or script used which key through subscriber IDs

Who it is for: Developers who want to run Hermes Agent or other OpenAI-compatible tools on pooled free-tier API keys.

How it fits with Hermes Agent

A general-purpose proxy that works as a backend for Hermes Agent and has its own docs/hermes-agent.md page; it also serves any other OpenAI-compatible tool.

How to install llm-keypool

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

uv tool install "llm-keypool[gui]"
pip install "llm-keypool[proxy]"
pip install "llm-keypool[all]"
pip install llm-keypool

Requirements: Python and free-tier API keys from supported providers such as Groq, Cerebras or Mistral; no paid API key needed

FAQ

What is llm-keypool?

llm-keypool is a free-tier LLM key pool manager. You register API keys once, and it rotates across them, handles rate-limit cooldowns and exposes a local OpenAI-compatible proxy.

Does llm-keypool work with Hermes Agent?

Yes. The README says to run the proxy and point Hermes Agent at it, so free-tier keys handle all LLM calls including delegated sub-agents. A docs/hermes-agent.md page covers the setup.

How do I install llm-keypool?

Install it from PyPI. The README recommends uv tool install "llm-keypool[gui]" for the TUI, pip install "llm-keypool[proxy]" for the proxy server, or pip install "llm-keypool[all]" for everything.