🔥 GrokRoute — Free AI Router for Grok Build

🔌 Multi-provider AI router for Grok Build.
Route Grok Build through free & local AI providers. Auto-fallback, zero config.

---

💡 What It Does

GrokRoute is a smart local proxy that sits between Grok Build and AI providers. It routes your requests to free cloud providers (Agnes, Groq, Zhipu, Laguna) or your local Ollama models — giving you more choice, better speed, and zero cost.

⚡ One command. Multiple providers. All the AI power.

npm install -g grokroute; grokroute install; grokroute

---

✨ Why GrokRoute?

	Default	GrokRoute
Cost	💸 Subscription	🆓 FREE
Providers	1 built-in	5+ with auto-fallback
Local models	❌ No	✅ Ollama
Offline mode	❌ No	✅ With Ollama
Privacy	Cloud-only	Your data → your choice
Admin UI	❌ CLI only	✅ Web UI at :8083/admin

---

🚀 Quick Start

# 1. Install globally
npm install -g grokroute

# 2. Auto-configure Grok Build to use the proxy
grokroute install

# 3. Launch!
grokroute
#    ^ press ENTER to start Grok Build — it now uses FREE providers!

That's it. Grok Build now runs through GrokRoute, routing to free providers automatically.

---

🔄 Smart Auto-Fallback

GrokRoute tries providers in priority order. If one fails, the next one takes over seamlessly:

Agnes AI  ──→  Groq  ──→  Zhipu  ──→  Laguna  ──→  Ollama
(fast,     (fastest,  (GLM,     (coding,    (local,
free tier) 280+ t/s)  free)     free tier)  fully free)

• Streaming mode: tries providers one by one, 5s timeout per attempt
• Non-streaming mode: parallel race — fastest good response wins 🏎️

---

💸 Providers

Provider	Free Tier	Speed	Sign-up
Agnes AI	✅ Free credits	⚡ Fast	apihub.agnes-ai.com
Groq	✅ Free tier	⚡⚡⚡ 280+ tok/s	console.groq.com
Zhipu AI	✅ Free GLM models	⚡ Medium	z.ai/model-api
Laguna	✅ Free tier	⚡ Medium	poolside.ai
Ollama	✅ Fully free	🖥️ Local	ollama.com

🔑 All providers offer free tiers. You can start with zero cost.

---

🎛️ Commands

Command	What it does
grokroute · groute · gfree	Start proxy → press ENTER to launch Grok Build
grokroute admin	Open web admin UI (configure keys visually)
grokroute install	Auto-configure ~/.grok/config.toml
grokroute status	Check proxy health & active provider
grokroute uninstall	Restore original Grok Build config

---

🖥️ Admin UI

Open http://127.0.0.1:8083/admin in your browser — configure all providers, test connections, and manage settings.

🎨 Modern dark-theme UI with real-time status, provider testing, and one-click save.

---

🏗️ Architecture

┌──────────┐     HTTP/SSE      ┌──────────────┐     API calls     ┌────────────┐
│ Grok     │ ────────────────→ │  GrokRoute   │ ────────────────→ │ Agnes AI   │
│ Build    │ ←──────────────── │   Proxy      │ ←──────────────── │ Groq       │
│ (client) │   OpenAI format   │  :8083       │   OpenAI format   │ Zhipu      │
└──────────┘                   │  Python 3.8+ │                   │ Laguna     │
                               │  + Node.js   │                   │ Ollama     │
                               └──────────────┘                   └────────────┘

• Zero external dependencies — the proxy is a single Python file
• Your prompts never leave your machine (except to the provider you choose)
• OpenAI-compatible API — works with any tool, not just Grok Build

---

⚙️ Configuration

// ~/.grokroute/grokroute-config.json
{
  "provider": "auto",
  "groq_api_key": "gsk_...",
  "groq_model": "llama-3.1-8b-instant",
  "agnes_api_key": "sk-...",
  "max_tokens": 4096,
  "temperature": 0.3,
  "enable_streaming": true
}

Or just use the Admin UI (grokroute admin) — no manual JSON editing needed.

---

🐧 Install Without npm

# Direct Python run — no Node.js needed
git clone https://github.com/wxstdo-boop/grokroute.git
cd grokroute
python grokroute-proxy.py

# Windows: run install.ps1 as admin, then start.bat

---

🧪 Tests

python tests/test_proxy.py
# ✓ /health
# ✓ /v1/models
# ✓ /v1/chat/completions (non-streaming)
# ✓ /v1/chat/completions (streaming)
# ✓ /admin UI loaded
# All tests passed.

---

🔧 Troubleshooting

Problem	Fix
"No provider available!"	Add at least 1 API key in admin UI or start Ollama
Port 8083 in use	Set GROK_FREE_PORT=8084 env var
Grok Build uses default API	Re-run grokroute install and restart Grok Build
Slow first response	Normal — proxy probes providers; cached after first request

---

🗺️ Roadmap

• Auto-fallback with sequential & parallel modes
• Web admin UI
• Ollama local model support
• Streaming SSE support
• Multi-provider race mode
• Docker image
• System tray app (Windows/Mac)
• Usage statistics dashboard
• Custom provider plugins

---

🤝 Contributing

PRs welcome! See CONTRIBUTING.md.

🔒 Security

See SECURITY.md.

📜 License

MIT — free as in freedom. Do whatever you want.

🌍 Languages

🇷🇺 Читать на русском

---

⭐ Star this repo if it saves you money!
_{Made with 🔥 by graysik & the open-source community}