<div align="center">

<img src="logo.webp" alt="GemiNitro" width="40" height="40" align="top"> GemiNitro

Production-grade Gemini API proxy with intelligent key pooling, quota management, and enterprise resilience features.

Pool multiple Gemini API keys with intelligent rotation strategies, automatic quota tracking, and comprehensive usage analytics. Built for reliability and scale.

</div>

---

What it does

GemiNitro is a production-grade reverse proxy for Google's Gemini API that sits between your AI coding agent (or any OpenAI-compatible client) and Google's Gemini API. It intelligently manages multiple API keys, tracks usage quotas, handles rate limits automatically, and provides comprehensive analytics.

Core Features

• Intelligent key rotation — weighted random, LRU, or sequential selection with configurable tolerance
• Cross-source routing — automatic fallback across API keys, Antigravity OAuth, and Gemini CLI OAuth
• Dynamic model discovery — per-key model fetching with 6-hour refresh, eliminates stale model errors
• Model aliasing — create user-friendly aliases (e.g., flash → gemini-2.0-flash)
• Priority tiers — free/standard/premium/enterprise with concurrency multipliers
• Usage quota management — per-model caps with per-account tracking and combined limits
• Quota groups — share limits across model variants (e.g., gemini-2.0-flash + gemini-2.5-flash)
• Background quota refresh — proactive 5-minute polling prevents rate limit errors for OAuth keys
• Automatic cooldown & retry — on 429 errors, marks key as cooling, tries next available key
• Duplicate detection — prevents adding the same API key or OAuth account twice
• OpenAI-compatible — works with /v1/chat/completions and any OpenAI SDK
• Native Gemini REST — also proxies /v1/models/{model}:generateContent paths directly
• Live web dashboard — real-time traffic, quota meters, key pool status, and system logs
• Comprehensive CLI — start, stats, install, key add/list/remove, alias, quota-group, and more
• Coding agent integration — one-command setup for OpenCode, Continue.dev, Aider, and others

---

Install

Option A — Let an LLM do it

Paste this into Claude Code, OpenCode, or any AI coding agent:

Install geminitro by following the instructions at:
https://raw.githubusercontent.com/jmvbambico/geminitro/main/README.md

Option B — Manual

git clone https://github.com/jmvbambico/geminitro.git
cd geminitro
npm install
npm link

# Start — creates .env with defaults if missing, detects first-run state, guides setup
geminitro start

A .env file with default values (PORT=7536, PROXY_API_KEY=geminitro, AUTO_UPDATE=false) is created automatically if missing. Customize it anytime.

geminitro start detects whether the server is configured. On first run it offers to register with your coding agent and add API keys via terminal or browser.

Get free Gemini API keys at aistudio.google.com. Multiple keys multiply your free-tier throughput.

---

First Run Flow

geminitro start
  ↓
Not registered to any coding agent?
  → Choose "Install now" → select agent → configure
Not registered?
  → Add your first key via terminal or browser setup wizard
Already configured?
  → Open browser dashboard or stay in terminal

---

Coding Agent Integration

Run geminitro install and select your agent. Supported agents:

| Agent | Config written | How to use | | ------------------ | ------------------------------------------------------- | ----------------------------------------- | | OpenCode | ~/.config/opencode/opencode.json or ./opencode.json | --model geminitro/<model> | | Continue.dev | ~/.continue/config.yaml | Select model in Continue's picker | | Aider | ~/.aider.conf.yml | Automatic — runs via GemiNitro by default | | Codex CLI | ~/.codex/config.toml | Automatic — uses configured provider | | OpenCrabs | ~/.opencrabs/config.toml + keys.toml | Select custom provider | | Kimi Code | ~/.kimi/config.toml | Uses geminitro provider | | Manual / Other | baseURL: http://localhost:7536/v1 | apiKey: geminitro |

Supported Capabilities

GemiNitro provides a high-fidelity translation layer between the OpenAI spec and Gemini's native features, ensuring advanced coding agents work out-of-the-box.

| Capability | OpenAI Format | Gemini/Claude Mapping | Status | | --------------------------- | ------------------------------------------ | ------------------------------------------- | ------ | | Tool Calls | tools[], tool_choice | functionDeclarations, toolConfig | ✅ | | Streaming Finish Reason | finish_reason: "tool_calls" | Signal emitted on terminal stream chunk | ✅ | | JSON Mode | response_format: { type: "json_object" } | responseMimeType: "application/json" | ✅ | | Reasoning / Thinking | reasoning_effort (o-series) | thinkingConfig (budget tokens) | ✅ | | Extended Thinking | thinking: { budget_tokens: N } | Claude thinkingBudgetTokens (passthrough) | ✅ | | Usage Stats | stream_options.include_usage | usageMetadata (tracked per-chunk) | ✅ | | Stop Sequences | stop: ["\n\nHuman:"] | stopSequences | ✅ | | Vision | image_url | inlineData / image parts | ✅ | | Structured Outputs | response_format: { type: "json_schema" } | responseSchema (Gemini 1.5/2.0) | ✅ |

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "geminitro": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "GemiNitro",
      "options": {
        "baseURL": "http://localhost:7536/v1",
        "apiKey": "geminitro"
      },
      "models": {
        "gemini-2.0-flash": {
          "name": "gemini-2.0-flash (GemiNitro)",
          "limit": { "context": 1048576, "output": 65536 }
        }
      }
    }
  }
}

Continue.dev

Appended to ~/.continue/config.yaml:

models:
  - name: GemiNitro / gemini-2.0-flash
    provider: openai
    model: gemini-2.0-flash
    apiBase: http://localhost:7536/v1
    apiKey: geminitro
    roles:
      - chat
      - edit
      - apply

Restart VS Code or reload the Continue extension to pick up the change.

Aider

Written to ~/.aider.conf.yml:

openai-api-base: http://localhost:7536/v1
openai-api-key: geminitro
model: gemini-2.0-flash

Codex CLI

Written to ~/.codex/config.toml:

provider = "openai"
model = "gemini-2.0-flash"

[providers.openai]
base_url = "http://localhost:7536/v1"
api_key = "geminitro"

OpenCrabs

Written to ~/.opencrabs/config.toml and ~/.opencrabs/keys.toml:

# config.toml
[providers.custom]
enabled = true
base_url = "http://localhost:7536/v1"
default_model = "gemini-2.0-flash"

# keys.toml (chmod 600)
[providers.custom]
api_key = "geminitro"

Kimi Code

Written to ~/.kimi/config.toml:

default_model = "geminitro"

[providers.geminitro]
type = "openai_legacy"
base_url = "http://localhost:7536/v1"
api_key = "geminitro"

[models.geminitro]
provider = "geminitro"
model = "gemini-2.0-flash"
max_context_size = 1048576
capabilities = ["thinking", "image_in"]

---

Web Dashboard

A live dashboard is served at http://localhost:7536/dashboard when the server is running.

• Overview — traffic stats, live traffic chart, usage quota meters, model distribution
• Usage Quotas — per-model quota progress bars with warning thresholds and reset timers
• API Keys — inline key table with status badges, priority tiers, add/remove keys
• System Logs — live log stream with type-colored rows and collapsible interface
• Settings — proxy API key management, quota reset schedule, server info
• Setup Wizard — browser-based first-run key setup at /dashboard/setup
• Themes — dark mode toggle + themeable OKLCH color palette
• Live updates — Socket.IO pushes key pool changes, traffic ticks, quota alerts, and log entries in real time

Build the dashboard from source:

npm run build

---

CLI Reference

geminitro start              Start the proxy (smart first-run flow)
geminitro start --no-splash  Start without splash screen
geminitro stop               Stop the running server
geminitro restart            Restart the server
geminitro status             Quick health check
geminitro stats              Terminal stats: quota usage (first), requests, keys, model usage, 7-day history
geminitro install            Register with a coding agent (interactive)
geminitro uninstall          Remove from all detected agent configs (auto-detected, one confirm)
geminitro update             Check for and apply the latest release
geminitro key add <k