quantum-hermes-free-router-kit - GitLite

KO | EN

gitlite — search

#editor #github #macos #claude #framework #agent #claude-code #swift #react #containers

quantum-hermes-free-router-kit

(★ 9)

Reusable starter kit for routing Hermes Agent through a local LiteLLM-based free/free-tier model router with clean aliases, fallback examples, systemd service templates, and terminal-first setup.

파일 탐색기

ZIP 다운로드

- - bug_report.md
  - feature_request.md
- - ci.yml
- pull_request_template.md
- ARCHITECTURE.md
- CONFIGURATION.md
- FAQ.md
- HERMES_INTEGRATION.md
- INSTALLATION.md
- LITELLM_ROUTING.md
- MODEL_STATUS_DISPLAY.md
- RELIABILITY.md
- SECURITY.md
- TROUBLESHOOTING.md
- env.example
- hermes-config-minimal.example.yaml
- hermes-provider-snippet.example.yaml
- litellm-config.example.yaml
- model-fallback-order.example.yaml
- hermes-nonstreaming-liteLLM-route.example.patch
- README.md
- doctor.sh
- install.sh
- uninstall.sh
- verify_repo.sh
- hermes-gateway.service.example
- quantum-hermes-router.service.example
- README.md
.env.example
.gitignore
CHANGELOG.md
CONTRIBUTING.md
LICENSE
README.md
ROADMAP.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

# 프로젝트 배지

License: MIT 바로가기
Awesome 바로가기

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> **⚡ A community starter kit for Hermes Agent users who want a local, free/free-tier model router using LiteLLM.**

---

## What This Is / Is Not

**This is:**

- A reusable configuration and script collection to set up a local LiteLLM proxy as a custom provider for Hermes Agent.
- A guide for routing Hermes model requests through one or more free/free-tier API providers with load balancing and fallback.
- A community resource — templates, docs, and examples that you can adapt to your own keys and providers.

**This is NOT:**

- An official Hermes Agent project. ([Hermes Agent](https://hermes-agent.nousresearch.com/) is the real thing.)
- An official LiteLLM project. ([LiteLLM](https://litellm.ai/) is the real thing.)
- A "hack" or workaround — it uses documented APIs and provider free tiers in full compliance with their terms.

---

## Architecture

```
User / Telegram
       │
       ▼
 Hermes Agent             ← Hermes CLI, Telegram bot, or SDK
       │
       ▼
 Hermes Gateway           ← Built-in Hermes routing layer
       │
       ▼
 custom provider          ← quantum_litellm (OpenAI-compatible, registered in ~/.hermes/config.yaml)
       │
       ▼
 LiteLLM Proxy            ← Local proxy at 127.0.0.1:4000/v1 — the only router
       │
       ▼
 Free/Free-Tier APIs       ← Gemini, OpenCode, Kilocode, and more
```

**Note:** There is no separate Quantum Router middleman. LiteLLM is the routing layer.

---

## Quick Start

```bash
# Clone
git clone https://github.com/spacepirate15/quantum-hermes-free-router-kit.git
cd quantum-hermes-free-router-kit

# Install
bash scripts/install.sh

# Configure your API keys
nano .env

# Diagnose
bash scripts/doctor.sh

# Start the proxy
.venv/bin/litellm --config config.yaml --port 4000

# Configure Hermes (see docs/HERMES_INTEGRATION.md)
# Then: your Hermes Agent will route through the local proxy automatically
```

---

## Documentation Map

| Document | What It Covers |
|----------|----------------|
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Full data flow, layers, why no middleman |
| [INSTALLATION.md](docs/INSTALLATION.md) | Prerequisites, platform notes, manual setup |
| [CONFIGURATION.md](docs/CONFIGURATION.md) | .env, config.yaml, Hermes provider config |
| [HERMES_INTEGRATION.md](docs/HERMES_INTEGRATION.md) | Registering quantum_litellm provider, model routing |
| [LITELLM_ROUTING.md](docs/LITELLM_ROUTING.md) | Routing rules, multi-key balancing, fallbacks |
| [RELIABILITY.md](docs/RELIABILITY.md) | Streaming issues, mitigations, advanced patches |
| [MODEL_STATUS_DISPLAY.md](docs/MODEL_STATUS_DISPLAY.md) | Monitoring router status and key usage |
| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common problems and fixes |
| [SECURITY.md](docs/SECURITY.md) | Secret management, audit patterns, disclosure |
| [FAQ.md](docs/FAQ.md) | Frequently asked questions |

---

## Key Features

- **Zero-cost routing** — Use free-tier API keys with intelligent load balancing.
- **Multi-key support** — Configure multiple keys for the same provider to stay within rate limits.
- **Automatic failover** — When one provider or key is exhausted, fall back to another.
- **Systemd integration** — Run as a background service on Linux (including WSL2).
- **Security-first** — Scripts audit for accidental secret commits; `.gitignore` protects `.env`.
- **Diagnosis tool** — `bash scripts/doctor.sh` checks your setup before you start.
- **Ubuntu/WSL2/macOS** — Cross-platform scripts with no destructive operations.

---

## Reliability Note for Telegram Long Tasks

If you use Hermes with Telegram and encounter "waiting for stream response" or "no chunks yet" errors on long tool-heavy tasks, see [RELIABILITY.md](docs/RELIABILITY.md). The recommended fix is to disable streaming in Hermes config:

```yaml
display:
  streaming: false
streaming:
  enabled: false
```

---

## Compliance

Only use API keys you own or are authorised to use. Always follow each provider's terms of service, quotas, rate limits, and acceptable-use policies.

Unapproved use of others' API keys, circumventing rate limits through deceptive means, or violating provider terms is never acceptable.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. We welcome improvements — issues, docs, scripts, examples.

---

## License

[MIT](LICENSE) — open source, community maintained.