nimbus-router

Nimbus ☁️

The puffy little router connects to everything.

⚖️ Legal & ToS Disclaimer

Nimbus is a Bring-Your-Own-Key (BYOK) tool. It does not circumvent authentication, pool keys across users, or provide API access on its own. It is a local routing utility. You are solely responsible for ensuring that your usage complies with the Terms of Service of each respective API provider you configure.

Before you commit to a paid API, you need to know your prompts actually work. But testing across nine providers — each with its own keys, rate limits, and context windows — is overhead that gets in the way of the actual work.

Nimbus removes that overhead. It runs locally, aggregates nine providers behind a single endpoint, and tells you exactly which model responded and how fast. Run the same prompt across providers, see what works, and iterate — without the setup friction slowing you down. That way when you’re ready to go to production, you already know your prompts hold up.

Nimbus is a lightweight, zero-dependency local proxy that runs on localhost:7766. You give it your API keys, and Nimbus handles the rest — exposing a single, unified, OpenAI-compatible endpoint that arbitrates between providers to deliver the fastest available response for testing.

Primary Use Case

Nimbus fits naturally into the prompt development workflow. Write a prompt, run it through Nimbus, and see how different models handle it. Adjust and rerun as you go. When you feel good about it, put it under some load and see how it holds up. By the time you reach for a production API key, you have a much clearer picture of what actually works — and what doesn’t.

---

📦 Step 0: Install Bun (30 seconds)

Nimbus runs on Bun — a fast, modern JavaScript runtime. Install it first:

Mac / Linux:

curl -fsSL https://bun.sh/install | bash

Windows (PowerShell):

powershell -c "irm bun.sh/install.ps1 | iex"

Restart your terminal after installing, then continue below.

---

🧠 Under the Hood (Built for Reliability)

This isn’t just a list of API endpoints. Nimbus is engineered for fault tolerance:

• Concurrent Speculative Execution: Uses a jittered Promise.any() stagger. If one provider hangs, it fires a fallback to the next while the first request is still pending. Nimbus returns the fastest successful response available.
• Micro-Mutex State Management: When 20 concurrent requests hit a 429 Rate Limit at the exact same millisecond, Nimbus queues the cooldown states safely to disk (~/.free-router/config.json) without race conditions.
• Auto-Quarantine: If a provider key dies (401/403), Nimbus instantly quarantines it, routes the prompt to the next provider, and appends a warning to your IDE output to keep your code generation running.
• Pre-Flight Context Estimation: A zero-dependency heuristic tokenizer calculates your prompt size before sending. It won’t waste time sending a 100k token codebase to an 8k context model.
• IDE-Native SSE Streaming: Fully implements the OpenAI Server-Sent Events (SSE) protocol so compatible clients remain stable. Nimbus buffers the provider response and streams it back to your IDE — a deliberate design choice for stability across all provider configurations.
• Session Affinity: Nimbus tracks which provider is winning for your current coding session (via system prompt fingerprint) and routes subsequent turns to the same provider — preventing quality drops mid-conversation.

---

🚀 Quick Start

Option 1: The One-Liner

bunx github:Jaax-Labs/nimbus-router

Option 2: Clone & Run

git clone https://github.com/Jaax-Labs/nimbus-router.git
cd nimbus-router
bun install
bun start

Nimbus will immediately launch an interactive setup wizard to collect your free API keys. It walks you through each provider one at a time, opens the signup page for you, and saves each key automatically. The whole process takes about 10–20 minutes.

---

✅ Verify It’s Working

After setup, before touching your IDE, confirm Nimbus is alive:

curl http://localhost:7766/health

You should see:

{
  "status": "ok",
  "port": 7766,
  "auth": "1 key(s) configured",
  "timestamp": "2026-02-28T00:00:00.000Z"
}

If you see a connection error: Nimbus may not be running. Start it with bun start.

---

🔌 Connecting to Your IDE

Once Nimbus is running, point your IDE at it:

• Base URL: http://localhost:7766/v1
• API Key: The sk-fr-... key shown at the end of setup
• Model: code, chat, or triage (or use any common model name — Nimbus aliases it automatically)

Step-by-step guides for each IDE:

IDE	Setup Guide
Cursor	docs/setup-cursor.md
Continue.dev	docs/setup-continue-dev.md
OpenCode	docs/setup-opencode.md
Zed	docs/setup-zed.md
Cline	docs/setup-cline.md
Kilo Code	docs/setup-kilo-code.md

---

➕ Adding More Providers

Skipped a provider during setup? Run:

bun add

This runs the wizard for only the providers you haven’t configured yet. Existing keys are untouched.

---

🔄 Resetting Your Config

Need to swap all keys or start completely fresh? Run:

bun reset

This wipes your saved config and re-runs the full setup wizard.

---

👻 Running in the Background (Daemonizing)

You don’t want to keep a terminal window open just to route your AI requests. Once Nimbus is running, background it:

Mac / Linux:

nohup bun start > nimbus.log 2>&1 &

(To stop it later: pkill -f "bun start")

Windows (PowerShell):

Start-Process bun -ArgumentList "start" -WindowStyle Hidden

---