[!IMPORTANT] Unofficial interoperability research project. Not affiliated with, endorsed by, or sponsored by Google. Using third-party clients or gateways may violate Google's Terms of Service—your accounts, your responsibility. You must supply your own eligible Google accounts and a compatible OAuth client profile; no credentials, tokens, or Google binaries are distributed. Read the full Disclaimer.

Why Gemini App2API?

_{🧢 MGGA — Make Gemini Great Again: A frontier GigaChad model trapped inside a consumer chat harness.}

Ever noticed how Gemini can feel constrained inside the consumer Gemini App—losing thread context or struggling to drive multi-step local engineering workflows? The bottleneck is rarely the base model; it is the consumer chat harness wrapped around it.

• Free the model into real engineering harnesses: Connect Cursor, Cline, Roo Code, OpenAI Codex CLI, PI-Desktop, Cherry Studio, or Open WebUI via standard /v1/chat/completions and /v1/responses endpoints while keeping full conversation history and local tool execution under your client's control.
• Native HTTP/2 protocol—not brittle web scraping: Communicates directly with Gemini's Robin HTTP/2 service using pure Node.js built-ins (node:http2, node:crypto), without headless browsers, cookie scraping, or patching local desktop binaries.
• Multi-account pooling for rolling usage windows: Intensive agentic coding can hit a single account's 5-hour or weekly window quickly. Pool multiple accounts you legitimately own with soft session affinity, read-only official usage bars, and configurable quota failover.
• Built to protect agent loops: Prevents coding agents from discarding 3,000+ bytes of streamed code or infinitely re-sending full conversation histories when upstream streams reset mid-turn (see Completion Contract).
• Honest upstream boundaries: Decoupling the local client harness does not bypass Google's servers—all upstream context limits, rate limits, safety filters, and account entitlements remain enforced by Google.

How It Compares

Key Features

• Scoped OpenAI Compatibility (Chat & Responses): Supports GET /v1/models, POST /v1/chat/completions, and POST /v1/responses with JSON or incremental SSE streaming, reasoning_effort / reasoning.effort mapping, and static PNG/JPEG/WebP image input.
• Caller-Owned Function Tools: Clients declare JSON Schema functions (including Responses type: "namespace" groups), execute approved calls locally, and replay results. The gateway validates every tool name and argument schema before emission—never executing shell commands or touching your workspace.
• Zero-Dependency, Security-First Runtime: Zero third-party production npm packages. Enforces 0700/0600 private state permissions, scrypt admin password hashing, SHA-256 API key lookup digests with 0600 private-state key storage (returned only at creation or via authenticated CSRF-protected reveal requests), strict Origin/Host/X-CSRF-Token admin protections, and SSRF-guarded opt-in remote image fetching.
• Bilingual Operations Console (English / 繁體中文): Inspect pool pulse and request-latency snapshot sparklines, review per-account Current usage / Weekly limit bars and model states in a slide-over inspector drawer, copy ready-to-paste client configs (Codex CLI, Cline, cURL), manage copyable client API keys, explicitly review or accept Gemini Terms of Service, and inspect sanitized HTTP/gRPC diagnostics across desktop and mobile.

Light Theme — Account Inspector & Pool Pulse	Mobile Console — Traditional Chinese (繁體中文)

Quick Start

1. Prerequisites

• Node.js 22+ (>= 22.0.0), npm, a modern browser, and a Google account with Gemini access (macOS or Linux).
• A compatible static OAuth client profile supplied from an authorized private source (not distributed in this repo; a Google AI Studio API key is a different service and cannot be substituted). Review the OAuth profile format and setup guide first.

2. Initialize and Start

From the repository root:

npm ci --omit=dev --ignore-scripts
export GATEWAY_DATA_DIR="$HOME/.gemini-app2api"

# Create a private 0600 .env without overwriting an existing one:
test -e .env || cp .env.example .env
chmod 600 .env
# Edit .env and set GATEWAY_ADMIN_PASSWORD to a unique 12–256 character secret.

node bin/gemini-gateway init
node bin/gemini-gateway import-profile < /private/path/oauth-profile.json
node bin/gemini-gateway start

Prefer Docker? Follow the hardened Docker Compose deployment guide (runs as uid 1000 with read-only rootfs, dropped capabilities, and loopback port publishing).

3. Sign In and Create a Client Key

Open http://127.0.0.1:18989/admin/ in your browser:

1. Sign in with your GATEWAY_ADMIN_PASSWORD (if left empty, passwordless admin is restricted strictly to loopback—see Remote access with TLS).
2. Under Accounts, click + Google sign-in and complete Google OAuth + MFA in your browser.
3. Click Test on the account card to verify live model access (note: Test sends one real request and uses quota; OAuth sign-in alone does not verify model entitlement).
4. Open API keys → Create key to generate and copy a client API key (you can copy, reveal, or revoke active keys there anytime).

Connect Your Client

Point any supported OpenAI-compatible client at your gateway:

Verify model discovery (zero quota used):

curl -fsS http://127.0.0.1:18989/v1/models \
  -H "Authorization: Bearer $GEMINI_GATEWAY_KEY"

Send a Chat Completions request (add "stream": true with curl -N for incremental SSE):

curl -fsS http://127.0.0.1:18989/v1/chat/completions \
  -H "Authorization: Bearer $GEMINI_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-argon","messages":[{"role":"user","content":"Hello!"}]}'

Client Setup Recipes

model = "gemini-hydrogen" # or "gemini-argon" for flagship Pro reasoning
model_provider = "gemini_app2api"
model_reasoning_summary = "none"
web_search = "disabled"

[model_providers.gemini_app2api]
name = "Gemini App2API"
base_url = "http://127.0.0.1:18989/v1"
env_key = "GEMINI_GATEWAY_KEY"
wire_api = "responses"

Models and Capabilities

Model aliases map to native Gemini App modes rather than pinned Google Cloud Vertex/AI Studio version strings, and model availability depends on each signed-in account's upstream entitlement. context_window: 128000 (gemini-argon) and context_window: 512000 (gemini-hydrogen) are empirical advisory client budgets calibrated to single-turn recall, prefill latency, and the gateway's 4 MiB request ceiling—not enforced token caps or official Google SLA guarantees.

Quota Consumption: gemini-argon vs gemini-hydrogen

[!WARNING] gemini-argon consumes roughly 60x more account quota than gemini-hydrogen on identical coding workloads. On a single Gemini AI Pro account, ~4-5 heavy (~15 KB output) coding turns on gemini-argon can exhaust an entire 5-hour rolling window (429 NATIVE_QUOTA_EXHAUSTED), whereas gemini-hydrogen fits ~290 heavy coding turns (or ~1,800 agent tool_call steps) in the same 5-hour window while responding ~2x-4x faster. Use gemini-hydrogen as your primary multi-step coding and tool-call workhorse, and reserve gemini-argon for architecture planning, hard debugging, or multi-account pooled setups (GATEWAY_QUOTA_FAILOVER=1).

Empirical GetUsageInfo measurements on identical non-dummy engineering turns (Gemini AI Pro accounts, Paid & Trial tiers observed at 1:1):

These figures are empirical observations via read-only GetUsageInfo telemetry (not official Google SLA figures), and upstream quota weights may change at any time.

Supported Capabilities

Security and Operational Principles

• Keep private state off Git and public networks: Never share .env, OAuth client profiles, refresh tokens, client API keys, or GATEWAY_DATA_DIR. See SECURITY.md.
• Client-owned history & permissions: The gateway never runs shell/file tools, never truncates or summarizes conversation history behind your back, and rejects silent upstream model downgrades.
• Explicit incomplete-turn semantics: Interrupted streams that already flushed usable output close cleanly with incomplete: true metadata so coding agents keep delivered work; always check incomplete when exact upstream completion matters. See COMPLETION_CONTRACT.md.
• Deliberate recovery budgets: Enabling GATEWAY_QUOTA_FAILOVER=1 or GATEWAY_AUTOMATIC_RECOVERY=1 helps survive single-account limits or transient resets, at the cost of additional upstream attempts when failures occur. See OPERATIONS.md and LOCKS_AND_LIMITS.md.

Documentation