Your coding agents. Your Gemini subscriptions. Zero-dependency native HTTP/2.
Use your eligible Google Gemini accounts in Pi, OpenClaw, Cursor, Cline, Roo Code, Codex CLI, and OpenAI SDKs—via standalone in-process plugins (no server needed) or a self-hosted Node.js gateway with multi-account pooling.
English · 繁體中文 · Quick Start · Connect Client · Models & Quota · API Reference · Operations
Important
Unofficial interoperability research project. Not affiliated with or endorsed by Google. Sign in personally with your own eligible Google accounts—no credentials, tokens, or Google binaries are distributed. Read DISCLAIMER.md.
| Host | Install | Sign In & Quota | Guide |
|---|---|---|---|
| Pi / GooeyPi | pi install npm:pi-gemini-app |
/login gemini-app · /gemini-quota |
extensions/pi/README.md |
| OpenClaw | openclaw plugins install npm:openclaw-gemini-app (or ClawHub) |
openclaw models auth login --provider gemini-app · /usage |
extensions/openclaw/README.md |
Both plugins run in-process over direct HTTP/2 (15s PING keepalives, HTTPS_PROXY support, 256 tools, parallel multimodal image uploads, automatic Free-tier gemini-auto filtering).
Requires Node.js >= 22 (macOS / Linux / WSL2) or Docker Compose, plus a Google account with Gemini access (AI Studio API keys are a different service).
Node.js:
git clone https://github.com/ShawTim/gemini-app2api.git && cd gemini-app2api
npm ci --omit=dev --ignore-scripts
npm startDocker Compose:
git clone https://github.com/ShawTim/gemini-app2api.git && cd gemini-app2api
read -r -s -p 'Admin password (>= 12 chars): ' GATEWAY_ADMIN_PASSWORD; echo
export GATEWAY_ADMIN_PASSWORD && docker compose up -d --buildOr run pre-built GHCR image directly (linux/amd64 & linux/arm64)
read -r -s -p 'Admin password (>= 12 chars): ' GATEWAY_ADMIN_PASSWORD; echo
docker run -d --name gemini-app2api --init --restart unless-stopped \
-p 127.0.0.1:18989:18989 -p 127.0.0.1:18765:18765 \
-v gemini-gateway-state:/data \
--read-only --cap-drop ALL --security-opt no-new-privileges \
--tmpfs /tmp:rw,noexec,nosuid,size=16m \
-e GATEWAY_HOST=0.0.0.0 -e GATEWAY_CALLBACK_HOST=0.0.0.0 -e GATEWAY_ALLOW_REMOTE=1 \
-e GATEWAY_PUBLIC_ORIGIN=http://127.0.0.1:18989 -e GATEWAY_ADMIN_PASSWORD \
ghcr.io/shawtim/gemini-app2api:latestSee Operations Guide for custom ports, TLS reverse proxies, and SSH tunneling.
Finish setup in browser: Open http://127.0.0.1:18989/admin/ → Accounts → + Google sign-in → click Test to verify entitlement → API keys → Create key.
| Setting | Value |
|---|---|
| Base URL | http://127.0.0.1:18989/v1 (or http://gateway:18989/v1 inside Compose / your HTTPS proxy URL) |
| API Key | Client key from API keys |
| Models | gemini-neon (flagship Pro; gemini-argon aliases here), gemini-hydrogen (fast), gemini-flash-lite |
| Endpoints | GET /v1/models · POST /v1/chat/completions · POST /v1/responses (full contract) |
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-neon","messages":[{"role":"user","content":"Hello!"}]}'Client Recipes — Codex CLI, Cursor, Cline / Roo Code, Cherry Studio, OpenAI SDKs
- OpenAI Codex CLI (
~/.codex/config.toml) — native/v1/responses+ namespace tools:model = "gemini-hydrogen" # or "gemini-neon" 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"
- Cline / Roo Code: API Provider
OpenAI Compatible, Base URLhttp://127.0.0.1:18989/v1, Modelgemini-hydrogenorgemini-neon. - Cursor: Settings → Models → add
gemini-neon/gemini-hydrogen→ Override OpenAI Base URL (HTTPS tunnel required if Cursor's cloud relay is active). - Cherry Studio / Open WebUI / SDKs: OpenAI provider with
http://127.0.0.1:18989/v1; seeexamples/client.mjsandexamples/client.py.
| Model | Role | Native Mode | Advisory context_window |
|---|---|---|---|
gemini-neon |
Gemini 4 Neon flagship Pro reasoning & coding (gemini-argon aliases here) |
PRO (3) |
512,000 |
gemini-hydrogen |
Gemini 4 Hydrogen low-latency reasoning (~1.7–2.6× faster, lighter quota) | FAST (1) |
512,000 |
gemini-flash-lite |
High-throughput lightweight tasks | 6 |
— |
Empirical GetUsageInfo observations on Gemini AI Pro accounts (neon_pro_policy; not official Google SLA figures):
| Workload | gemini-hydrogen |
gemini-neon |
Neon Multiple |
|---|---|---|---|
Massive code review + rewrite (thinking=2) |
~0.12% weekly (~76s) |
~0.25% weekly (~198s) |
~2.0× |
Multi-tool agent tool_call step (thinking=2) |
~0.024% weekly (~8s) |
~0.037% weekly (~14s) |
~1.56× |
Standard ~14 KB plan (thinking=0) |
~0.017% weekly (~28s) |
~0.086% weekly (~36s) |
~5.1× |
| Est. 5-hour single-account capacity | ~40 rewrites / ~210 tool steps |
~20 rewrites / ~135 tool steps |
— |
MGGA — Make Gemini Great Again: Free frontier Gemini models from a consumer chat harness into real engineering tools.
| Dimension | Gemini App2API | Web / Cookie Scrapers | Desktop Injection / MITM |
|---|---|---|---|
| Transport | Pure Node.js native HTTP/2 (ProcessQuery) + parallel image uploads |
Fragile DOM / browser cookies | Binary hooks / local MITM |
| Auth & Pool | Standard Google OAuth (0600 local state), multi-account failover & quota bars |
Frequent cookie expiry / CAPTCHA | Single active desktop GUI |
| Agent Safety | Schema-validated tools (256 declarations), hallucinated tool-result suppression, incomplete: true contract |
Unvalidated regex / broken loops | Consumer UI limits |
| Footprint | Node.js >= 22, 0 production npm dependencies |
Playwright / Python stacks | OS & binary version locked |
Highlights:
- Resilient HTTP/2 & Proxy Support:
15sHTTP/2PING+ TCP keepalives, zero-dependencyHTTPS_PROXY/HTTP_PROXY/NO_PROXYCONNECTtunneling, retryable503 SERVER_SHUTDOWNrestarts, and bounded automatic recovery. - Built for Long E2E & Agent Loops: Up to
256caller tool declarations (512 KiB/16,384nodes), structured outputs (json_schema/json_object), opt-innative_searchcitations, and parallel HTTP/2 multimodal image uploads (256images /20 MiBper image safety bounds + per-account in-memoryblobIdcaching). - Zero-Dependency Security & Bilingual Console:
0700/0600private state,scryptadmin auth, SHA-256 key vault, CSRF/Origin guards, and live per-account × per-model telemetry (English/繁體中文, zero prompt logging).
More Console Screenshots (Light Theme & Mobile 繁體中文)
| Light Theme — Account Inspector | Mobile — Traditional Chinese (繁體中文) |
|---|---|
![]() |
![]() |
| Document | Contents |
|---|---|
Pi Extension (extensions/pi/README.md) |
Standalone pi-gemini-app plugin for Pi Coding Agent & GooeyPi |
OpenClaw Plugin (extensions/openclaw/README.md) |
Standalone openclaw-gemini-app provider plugin for OpenClaw & ClawHub |
API Support (docs/API_SUPPORT.md) |
Endpoints, tools, structured outputs, images, native_search, error codes |
Operations (docs/OPERATIONS.md) |
.env config, Docker Compose, TLS reverse proxy, launchd, troubleshooting |
Completion Contract (docs/COMPLETION_CONTRACT.md) |
Partial-output preservation, zero-output GENERATION_FAILED, agent loop safety |
Account Lifecycle (docs/ACCOUNT_LIFECYCLE.md) · Limits (docs/LOCKS_AND_LIMITS.md) |
OAuth, ToS consent, quota telemetry, concurrency & payload bounds |
Testing (docs/CURRENT_CONTRACT_TESTS.md) · Security (SECURITY.md) · Changelog (CHANGELOG.md) |
Offline E2E suites, security model, release history |
MIT License · Disclaimer · Security Policy · Contributing
Unofficial self-hosted interoperability software. No Google binaries, credentials, tokens, accounts, or quota are distributed.



