{"id":50870773,"url":"https://github.com/polarisagi/hermes","last_synced_at":"2026-06-15T05:01:28.829Z","repository":{"id":363068302,"uuid":"1261835298","full_name":"polarisagi/hermes","owner":"polarisagi","description":"A universal, highly intelligent LLM API proxy gateway. Seamlessly translates heterogeneous AI protocols (OpenAI, Anthropic, Gemini) with built-in multi-account rotation, circuit breaking, and zero-config deployment.","archived":false,"fork":false,"pushed_at":"2026-06-15T03:32:34.000Z","size":750,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T04:19:53.007Z","etag":null,"topics":["ai-agent","ai-gateway","anthropic","api-proxy","deepseek","gemini","golang","llm","llm-ops","load-balancing","openai-api","vertex-ai"],"latest_commit_sha":null,"homepage":"https://polarisagi.online/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polarisagi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-07T08:02:14.000Z","updated_at":"2026-06-15T03:32:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/polarisagi/hermes","commit_stats":null,"previous_names":["polarisagi/hermes"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/polarisagi/hermes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarisagi%2Fhermes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarisagi%2Fhermes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarisagi%2Fhermes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarisagi%2Fhermes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polarisagi","download_url":"https://codeload.github.com/polarisagi/hermes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarisagi%2Fhermes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34348292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-gateway","anthropic","api-proxy","deepseek","gemini","golang","llm","llm-ops","load-balancing","openai-api","vertex-ai"],"created_at":"2026-06-15T05:00:41.130Z","updated_at":"2026-06-15T05:01:28.821Z","avatar_url":"https://github.com/polarisagi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PolarisAGI-Hermes 🌌\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/polarisagi/hermes)](https://goreportcard.com/report/github.com/polarisagi/hermes)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![Release](https://img.shields.io/github/v/release/polarisagi/hermes)](https://github.com/polarisagi/hermes/releases)\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🇬🇧 English\u003c/strong\u003e | \u003ca href=\"README_zh.md\"\u003e🇨🇳 简体中文\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**PolarisAGI-Hermes** is a lightweight, highly intelligent **Universal LLM API Proxy \u0026 Concurrency Control Gateway**. \n\nOriginally designed as a Google Vertex AI adapter, it has completely evolved into a **Universal AI Gateway**. It natively supports proxying, format conversion, and routing across almost all mainstream protocols (OpenAI, Google Gemini, Google Agent Platform, Anthropic, and Local models like Ollama/vLLM). It comes with a massive built-in dictionary covering **30+ global model providers** out-of-the-box. \n\nIt completely solves business interruptions caused by API Key rate limits, bans, or depleted balances by utilizing multi-account rotation and intelligent concurrency queuing. The latest version is purely **Zero-Config**, driven by an embedded **SQLite** database, and comes with a built-in **Web Admin Dashboard**.\n\n\u003e **🌟 Why the name Hermes?**\n\u003e In Greek mythology, Hermes is the swift messenger of the gods and the patron of boundaries. Similarly, **PolarisAGI-Hermes** acts as the ultimate \"messenger\" in the AI world—seamlessly translating complex, heterogeneous AI protocols (OpenAI, Anthropic, Gemini) and guiding requests swiftly and reliably across boundaries, breaking the silos between different AI providers.\n\n---\n\n### ✨ Core Features\n\n1. **🔑 One-Click Client Auto-Config (Highly Recommended!)**\n   Break the restrictions of commercial AI clients (like Claude Code, Codex, Cursor) that lock you into official APIs! The Admin Panel lets you instantly inject PolarisAGI-Hermes proxy settings, **allowing you to freely use your own API Keys and third-party models in closed software.**\n   \u003e 🔥 **Pro Tip: We highly recommend pairing this with [DeepSeek](https://platform.deepseek.com)**! DeepSeek is fully compatible with the OpenAI protocol and offers incredible performance at a disruptive price. When combined with PolarisAGI-Hermes' multi-account rotation and circuit breakers, you achieve the ultimate seamless AI coding experience.\n\n2. **🌐 Universal Protocol \u0026 Provider Support**\n   Includes a built-in, ready-to-use dictionary of 30+ global AI providers (OpenAI, Anthropic, DeepSeek, Zhipu, Moonshot, Qwen, Doubao, Mistral, Groq, SiliconFlow, etc.). No need to manually dig up Base URLs anymore.\n\n3. **🎛️ Simple / Pro Dual-Mode UI**\n   **Simple Mode**: Streamlined forms for quick setup. **Pro Mode**: Unlocks full control over concurrency limits, billing alerts, intelligent retries, and advanced model mappings.\n\n4. **🔀 Dual-Track Model Mapping Engine**\n   - **Minimalist Mode (Intelligent Semantic Mapping)**: Automatically identifies model tiers and intelligently maps cross-protocol requests transparently.\n   - **Pro Mode (1-to-1 Exact Mapping)**: Allows manual hardcoded routing rules with Regex support for absolute control.\n\n5. **🛡️ Multi-Account Pool \u0026 Single Concurrency Isolation**\n   Requests are queued based on physical accounts. Strict physical-level single-concurrency isolation prevents API bans (especially crucial for Google/Anthropic endpoints).\n\n6. **⚡ 5-State Circuit Breaker \u0026 Auto-Retry Rotation**\n   🟢 Idle → 🟡 Busy → 🔴 Cooldown → 🟠 Probation → ⚫ Exhausted. A built-in gateway retry loop handles upstream 429/5xx errors by seamlessly rotating to backup nodes while applying exponential backoff to failing nodes, ensuring graceful recovery.\n\n7. **💰 Billing \u0026 Quota Management**\n   Tracks token usage via SQLite. Supports setting maximum spend percentages to auto-disable accounts near exhaustion.\n\n8. **🚀 Zero Dependency Deployment**\n   Single binary, built-in Web UI, embedded DB migrations. Just run it!\n\n---\n\n### 🔀 Protocol Route Matrix\n\n| Source Protocol (Client) | Target Protocol (Upstream) | Description |\n|--------------------------|----------------------------|-------------|\n| openai                   | openai                     | Passthrough + Rotation (Works for all OpenAI-compatible APIs) |\n| openai                   | anthropic                  | OpenAI → Anthropic format conversion |\n| openai                   | google                     | OpenAI → Google Gemini / Agent Platform conversion |\n| anthropic                | anthropic                  | Passthrough + Rotation |\n| anthropic                | openai                     | Anthropic → OpenAI format conversion |\n| anthropic                | google                     | Anthropic → Google format conversion |\n| google                   | google                     | Passthrough + Rotation |\n| local                    | local                      | Local model passthrough (Ollama/vLLM, no auth) |\n\n---\n\n### 📂 Default Directory\nAll configurations, billing records, and SQLite databases (`polarisagi_hermes.db`) are safely stored in:\n`~/.polarisagi/hermes/`\n\n---\n\n### 🚀 Quick Install\n\n\u003e **💡 Network Connectivity Notice**: Our installation scripts have a built-in **smart fallback mechanism for Mainland China users**. If the script detects a GitHub timeout, it will automatically switch to a domestic proxy node (`ghproxy.net`) to ensure a smooth download.\n\n**macOS / Linux:**\n```bash\n# Recommended (Includes smart network fallback)\ncurl -sSL https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/install.sh | bash\n\n# Mainland China Fallback 1 (ghfast mirror)\ncurl -sSL https://ghfast.top/https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/install.sh | bash\n\n# Mainland China Fallback 2 (ghproxy mirror)\ncurl -sSL https://mirror.ghproxy.com/https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/install.sh | bash\n```\n\n**Windows:**\n```powershell\n# Recommended (Includes smart network fallback)\nirm https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/install.ps1 | iex\n\n# Mainland China Fallback 1 (ghfast mirror)\nirm https://ghfast.top/https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/install.ps1 | iex\n\n# Mainland China Fallback 2 (ghproxy mirror)\nirm https://mirror.ghproxy.com/https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/install.ps1 | iex\n```\n*The gateway will run as a background service and auto-start on user logon.*\n\n---\n\n### 🛠️ Getting Started\n\nBy default, the gateway listens on `127.0.0.1:27777`.\n\n1. **Admin Panel**: Visit [http://127.0.0.1:27777](http://127.0.0.1:27777)\n2. **Add Channel**: Select Protocol → Choose Provider → Enter API Key → Save.\n3. **One-Click Client Config**: Navigate to \"Client Config\", pick your target software, select your injected API key, and you're done!\n4. **API Endpoints** (Point your AI tools to these URLs, API Key can be any dummy text):\n   - OpenAI Protocol: `http://127.0.0.1:27777/v1/openai/`\n   - Anthropic Protocol: `http://127.0.0.1:27777/v1/anthropic/`\n   - Google Protocol: `http://127.0.0.1:27777/v1/google/`\n\n---\n\n### 🧪 Local Testing Mode \n\nWhen testing modified gateway code locally, please use test mode (listens on port `28889`) to avoid conflicts with your running production instance:\n\n```bash\nmake run-test\n# Or manually:\nTEST_MODE=true go run ./cmd/hermes\n```\n\n---\n\n### 🗑️ Uninstall\n\n**macOS / Linux:**\n```bash\n# Default\ncurl -sSL https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/uninstall.sh | bash\n\n# Mainland China Fallback 1 (ghfast mirror)\ncurl -sSL https://ghfast.top/https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/uninstall.sh | bash\n\n# Mainland China Fallback 2 (ghproxy mirror)\ncurl -sSL https://mirror.ghproxy.com/https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/uninstall.sh | bash\n```\n**Windows:**\n```powershell\n# Default\nirm https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/uninstall.ps1 | iex\n\n# Mainland China Fallback 1 (ghfast mirror)\nirm https://ghfast.top/https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/uninstall.ps1 | iex\n\n# Mainland China Fallback 2 (ghproxy mirror)\nirm https://mirror.ghproxy.com/https://raw.githubusercontent.com/polarisagi/hermes/main/scripts/uninstall.ps1 | iex\n```\n\u003e **Note**: Uninstalling only removes the service and binary. Data remains safely in `~/.polarisagi/hermes/`. Delete it manually if you want a complete wipe.\n\n---\n\n### 📄 License\nGNU Affero General Public License v3.0 (AGPL-3.0). *(If you use this code, please retain the original author credit: `mrlaoliai`)*\n\n---\n\n### 🌐 Links \u0026 Contact\n* **Official Website**: [https://polarisagi.online/](https://polarisagi.online/)\n* **GitHub Repository**: [https://github.com/polarisagi/hermes](https://github.com/polarisagi/hermes)\n* **Author / Creator**: `mrlaoliai` (Find me on Xiaohongshu, Douyin, TikTok, and X)\n* **Contact Email**: [polarisagi.online@gmail.com](mailto:polarisagi.online@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolarisagi%2Fhermes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolarisagi%2Fhermes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolarisagi%2Fhermes/lists"}