Gemini Proxy¶

OpenAI-compatible API proxy for Google Gemini image and text generation, powered by your existing Gemini Pro subscription.

Personal use only

Gemini Proxy authenticates using your browser's Google session cookies. It must only run on machines you personally control. Never deploy this on shared infrastructure or expose it to the public internet. See Security for details.

What it does¶

Gemini Proxy translates OpenAI v1 API calls into Google Gemini requests, letting you use Gemini through any OpenAI-compatible client — Open WebUI, LangChain, custom scripts, or AI coding agents via MCP.

graph LR
    A[OpenAI Client] -->|/v1/chat/completions| B[Gemini Proxy]
    C[Open WebUI] -->|/v1/images/generations| B
    D[Claude / IDE] -->|MCP stdio| B
    B -->|Browser cookies| E[Google Gemini]

Features¶

OpenAI v1 API — drop-in /v1/chat/completions, /v1/images/generations, /v1/models
Image generation — Gemini's native image model through the standard OpenAI images endpoint
SSE streaming — streaming chat completions via Server-Sent Events
Cookie-based auth — automatic extraction from Brave/Chrome, with a systemd timer for periodic refresh
Staleness detection — /health endpoint reports cookie age; returns 503 with Retry-After when stale
MCP server — Model Context Protocol (stdio) for agent integration in Claude Code, Cursor, and others
systemd deployment — user-level service with crash recovery and loginctl linger persistence

How authentication works¶

Unlike cloud API proxies that use API keys, Gemini Proxy uses your browser's session cookies (__Secure-1PSID, __Secure-1PSIDTS) to authenticate with Google Gemini. This means:

No API key needed — your Gemini Pro subscription is the credential
Cookies expire — a systemd timer extracts fresh cookies from your browser every 12 hours
Single-user by design — the proxy operates as you, with your Google account's permissions and rate limits

Read the Security page to understand the trust model before deploying.

Quick start¶

git clone https://github.com/jaigouk/gemini-proxy.git
cd gemini-proxy
uv sync

# Extract cookies from your browser
python scripts/extract_cookies.py

# Start the server
uv run python main.py --mode api --host 0.0.0.0 --port 8989

Then point your OpenAI-compatible client to http://<your-ip>:8989/v1.

See Getting Started for the full setup guide.