gemini-stealth-bridge (gsb)

OpenAI-compatible proxy for Gemini Web. Connect coding agents and other API clients to your Gemini account through Chat Completions or Responses endpoints.

gsb translates OpenAI-style messages, images, and tool definitions into Gemini Web requests, then converts the results back into JSON or Server-Sent Events (SSE). It authenticates with your Google session cookies, not a Gemini Developer API key. Model access and quotas depend on the connected account.

The daemon runs without headless Chrome or CDP. Browserless transport is an implementation detail; the API bridge is the interface your clients use.

• Capabilities and limits
• What's new in v0.2.0
• Quick start
• Account setup
• Client integration
• API usage
• Authentication and security
• Configuration
• Operations and troubleshooting
• How it works
• Development
• License

This is an unofficial bridge to the Gemini web app, not Google's supported Gemini Developer API or an OpenAI service. Changes to Google's web protocol, sign-in requirements, account restrictions, and quotas can interrupt operation. The transport does not guarantee protection from detection or account restrictions. Use only accounts you are authorized to access and review Google's applicable terms.

Compatibility covers the endpoints and fields described below, not the entire OpenAI API:

• Sampling and output controls such as temperature, top_p, max_tokens, and max_output_tokens are not forwarded as generation controls. Do not rely on them to enforce output limits.
• Responses clients must send conversation history in input; previous_response_id is not a continuation mechanism here. Response retrieval, deletion, and background jobs are not implemented.
• Function calling is prompt-based, not native Gemini Developer API function calling. Malformed or schema-invalid calls can fail with tool_call_error. Native Gemini web tools are disabled for generation; OpenAI built-in tools such as web search are not exposed.
• Token usage is estimated locally, not reported by Google's billing/tokenizer API. The model registry advertises a 1,048,576-token context window and 65,536-token output limit as metadata, not a guarantee for every account or request.
• Audio, video, image generation, embeddings, and the OpenAI Files API are not exposed. Internal text-attachment offloading is not a general file-upload API.

Version 0.2.0 focuses on coding-agent workflows, multi-account reliability, stream correctness, and long-session stability:

• Reliable pool routing and account isolation: BRIDGE_ACCOUNT_STRATEGY supports rotate (default sticky session), lru, and fill-first with BRIDGE_ACCOUNT_PRIORITY. Pool-key requests can fail over before response output is committed; account keys (gsb-<name>) remain pinned and never switch accounts on quota, substitution, authentication, timeout, or network errors.
• Fail-closed streaming for long reasoning turns: The default verified stream waits for the requested model identity before sending model output. After headers, reasoning, text, or a tool call is committed, retries and failover stop, preventing mixed answers across attempts. SSE keep-alives keep long thinking requests alive through reverse proxies.
• Live prose streaming while tools are enabled: When a turn answers in prose (summaries, explanations, no tool call), text longer than 320 bytes streams live without waiting for the turn to close — pre-tool preamble text included. Any tool envelope that appears before the final tool call is held back so clients never see stale commands; final content stays in sync with the committed turn.
• Prose that mentions tool envelopes is not malformed: Parser detection is stricter about stand-alone fenced envelopes, so summaries quoting the {"tool_calls":[...]} format (in code fences or inline backticks) pass through as answer text instead of failing hard. Mid-sentence <think>…</think> tags are preserved in answer text and only routed to reasoning_content when they are real thinking blocks.
• Account status and quota recovery that reflect reality: /v1/accounts and gsb --accounts (--accounts-live) expose computed health states and the rolling quota window. Repeated substitution failures back off to hour-scale intervals when they indicate a weekly limit, expired synthetic cooldowns no longer deadlock accounts, and pool errors summarize unavailable-account reasons without exposing credentials.
• More reliable long conversations: Continuation metadata is reused with bounded LRU behavior, broken entries are invalidated before a full-prompt retry, and oversized history can be offloaded instead of forcing every turn inline. Cache hit accounting now separates real continuation use from account-affinity scans.
• Safer tool calls and Responses history: Tool arguments are validated incrementally and compared by parsed JSON, so upstream revisions fail closed instead of leaking stale or concatenated arguments. /v1/responses canonicalizes assistant text and function calls so multi-turn tool conversations preserve their continuation history.
• Model metadata and reasoning output match upstream behavior: /v1/models reports per-model token limits, advertised thinking levels, and the configured default. Inline thought blocks, including multilingual and CJK forms, are routed to reasoning_content instead of being mixed into the final answer.
• Simpler account setup across browsers and operating systems: gsb --login <name> is the primary sign-in path. Cookie import now supports signed-in profile detection, stale-session guidance, Arc on macOS and Windows, and macOS Keychain safe-storage decryption.

Requires Go 1.26.0 or newer, Git, and an account that can use Gemini Web. Shell examples use a POSIX shell; on Windows, run the binary as gsb.exe and adapt environment-variable assignments to your shell.

git clone https://github.com/azrinaldi/gemini-stealth-bridge.git
cd gemini-stealth-bridge
go build -o gsb ./cmd/gsb

Alternatively, install into your Go binary directory and use gsb instead of ./gsb:

go install github.com/azrinaldi/gemini-stealth-bridge/cmd/gsb@latest

Sign in through gsb so the session is created by a real sign-in. This is the recommended path:

./gsb --login acc1

A browser opens on Gemini Web. Complete Google sign-in (including 2FA), send one message in Gemini, then press Enter in the terminal to capture the session.

If you already have a browser profile signed in to Gemini and prefer to reuse it, import its cookies instead:

./gsb --import-chrome acc1

For a non-default profile, add --chrome-profile "Profile 4". If browser-cookie decryption is unavailable, use a cookie export instead.

./gsb --probe

Inspect the account's discovered model IDs and quota information. A successful import does not imply access to every Gemini model.

./gsb

The default address is http://127.0.0.1:20133. Keep this default local-only setup on loopback; see Authentication and security before sharing access.

There are two kinds of key. Pick one:

List the models available to the pool:

curl -sS http://127.0.0.1:20133/v1/models \
  -H 'Authorization: Bearer public'

Set MODEL to an id returned by that endpoint. gemini-flash below is an example, not a promise of availability:

export MODEL=gemini-flash
curl -sS http://127.0.0.1:20133/v1/chat/completions \
  -H 'Authorization: Bearer public' \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK.\"}]}"

Read the answer from choices[0].message.content. /health checks that the daemon is running; only a successful model request verifies upstream generation.

X-GSB-Account in the response headers names the account that served the request, which is the quickest way to see the pool working. Replace public with gsb-acc1 to pin the same request to one account.

Each imported account is stored in ~/.gemini-stealth-bridge/accounts/<name>.json, or under $BRIDGE_HOME/accounts/ when configured. Names accept 1-64 characters from A-Z, a-z, 0-9, ., _, and -.

Cookie imports bootstrap the account against Gemini Web before reporting success. Treat both source cookie exports and saved account files as credentials.

./gsb --login acc1

The helper opens Gemini Web and waits for terminal input. Sign in, then press Enter to import from the selected local profile, or paste a cookie header / single-line JSON export. It does not automatically detect completion of login. Without a profile hint, the opened default browser and the auto-detected cookie profile may differ.

Prefer --login over copying cookies out of a browser that was never signed in to Gemini. A profile that has not completed Google sign-in holds cookies that expire within minutes, so an import can look successful and then fail almost immediately with 401 upstream_auth_error or code 1016. Signing in first, then capturing, is the reliable path:

1. Run ./gsb --login <name> and complete Google sign-in in the opened browser, including any 2FA or "verify it's you" prompt.
2. Open https://gemini.google.com/app and send one message, so the session is fully established.
3. Press Enter in the terminal to capture the session.
4. Run ./gsb --probe and confirm the account reports models without an auth error.

If an account later starts failing with an expired-session error, repeat the login instead of re-exporting the same stale cookies. ./gsb --rotate only renews rotating cookies such as __Secure-1PSIDTS; it cannot restore a revoked or never-established sign-in.

Despite its name, --import-chrome also recognizes other Chromium browsers and Firefox cookie databases. No browser is launched during import. Use this only when that browser profile is already signed in to Gemini.

# Auto-detect a local cookie database.
./gsb --import-chrome acc1

# Choose a profile by name.
./gsb --import-chrome acc1 --chrome-profile "Profile 4"

# Choose a profile directory or cookie database explicitly.
./gsb --import-chrome acc1 --cookie-db "$HOME/.config/google-chrome/Default"

--chrome-profile also accepts a directory or cookie database path. --cookie-db takes precedence when both are supplied.

Arc is supported too. On macOS its profile lives at ~/Library/Application Support/Arc/User Data; on Windows it lives under the MSIX package directory %LOCALAPPDATA%\Packages\TheBrowserCompany.Arc_*\LocalCache\Local\Arc\User Data (auto-detected via glob):

# macOS
./gsb --import-chrome acc1 --cookie-db "$HOME/Library/Application Support/Arc/User Data/Default"

# Or just name the browser and let gsb find the profile.
./gsb --import-chrome acc1 --chrome-profile arc

When no profile is given, auto-detection scans every known browser and prefers the first database that actually contains a SAPISID cookie, so an unsigned-in Chrome install no longer shadows a signed-in Arc, Brave, or Edge profile.

Decryption depends on the browser, OS, and access to the browser's encryption keys. Linux keyring-backed cookies may require secret-tool and an unlocked desktop keyring. On macOS gsb queries the login Keychain for the matching <Browser> Safe Storage item (Chrome Safe Storage, Arc Safe Storage, Brave Safe Storage, …) and macOS asks you to allow access the first time; CHROME_PASS overrides the lookup when Keychain access is unavailable. Windows DPAPI decryption requires the same Windows user context; App-Bound (v20) encryption requires a manual export. A detected database is not a guarantee that its cookies can be decrypted.

Import either a raw Cookie header value or a Cookie-Editor JSON array:

./gsb --import-cookie acc1 --cookie-file /path/to/cookies.json

The same payload can be supplied on stdin:

./gsb --import-cookie acc1 < /path/to/cookies.json

--cookie-value accepts an inline payload, but puts credentials in shell history and potentially process listings. Prefer a protected file or stdin. Export the Google cookies used by the authenticated Gemini session; an incomplete or expired export will not bootstrap successfully.

Repeat the login with another name:

./gsb --login acc2

Or, if that account is already signed in to a different browser profile:

./gsb --import-chrome acc2 --chrome-profile "Profile 2"

Each account has its own cookie state, model list, quota state, and transport session. Multiple files belonging to the same Google account may be deduplicated; additional files do not create additional upstream quota.

Configure any client that supports a custom OpenAI-compatible endpoint:

Choose Chat Completions for clients that consume choices / tool_calls, or Responses for clients that consume output items and response.* events. Client support for reasoning fields varies. OpenAI compatibility does not imply that every coding agent or every client-specific feature has been tested.

Add gsb as an OpenAI-compatible provider in 9router:

Add a separate provider credential for each account if you want the router to manage account selection. Point the coding agent at the router's URL with the router's own API key; use the model name/prefix exposed by the router, for example gsb/gemini-flash. The bridge also accepts the gsb/ model prefix directly.

Prefer one connection with the pool key. Account rotation belongs to gsb because it is the only component that knows per-account quota, quarantine state, and conversation continuation affinity. A router that spreads requests across per-account connections cannot see any of that: it only learns about exhaustion from a 429, and it will move the next turn to a different account, discarding the cached Gemini session. Use per-account connections only when you deliberately want to pin traffic to one account.

The base URL must be reachable from the router process. Inside a container, 127.0.0.1 refers to that container, not the host running gsb. Any non-loopback deployment needs the security measures below. If your router caches or overrides model metadata, verify what survives:

# Check the bridge alone (all fields required)
./scripts/check-router-metadata.sh http://127.0.0.1:20133 public

# Compare the bridge against the router; reports exactly which fields the router dropped
./scripts/check-router-metadata.sh --compare \
  http://127.0.0.1:20133 http://127.0.0.1:20130 - sk-router-key

The compare form distinguishes a bridge problem from a router problem. A router that drops capabilities.thinkingLevels is why a harness cannot render a low/medium/high selector, and the script names that field rather than blaming the bridge.

The following examples assume the daemon is running, acc1 is imported, and MODEL is set to an available model as shown in the quick start. They use gsb-acc1 so the account serving each request is predictable. Replace it with your pool key (BRIDGE_API_KEY, public by default) to let gsb rotate across accounts.

Use curl -N to avoid buffering SSE output:

curl -N -sS http://127.0.0.1:20133/v1/chat/completions \
  -H 'Authorization: Bearer gsb-acc1' \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL\",\"stream\":true,\"reasoning_effort\":\"high\",\"messages\":[{\"role\":\"user\",\"content\":\"Explain how this bridge works.\"}]}"

Chat streams emit chat.completion.chunk objects and finish with data: [DONE]. Text uses choices[].delta.content; reasoning, when extracted and enabled, uses the extension choices[].delta.reasoning_content. Tool calls use choices[].delta.tool_calls.

curl -sS http://127.0.0.1:20133/v1/responses \
  -H 'Authorization: Bearer gsb-acc1' \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL\",\"instructions\":\"Keep answers concise.\",\"input\":\"Explain how this bridge works.\"}"

Read the result from the returned output items. Set stream: true for events including response.created, response.output_text.delta, response.reasoning_summary_text.delta, response.function_call_arguments.delta, and response.completed.

For multi-turn calls, resend the conversation in input, including assistant output and any function_call / function_call_output items. The bridge's internal continuation cache is separate from OpenAI's previous_response_id feature.

• For Chat Completions, supply function tools using tools: [{"type":"function","function":{"name":"get_status","description":"Read service status","parameters":{"type":"object","properties":{},"additionalProperties":false}}}]. Responses accepts flat function definitions with type, name, description, and parameters.
• tool_choice supports auto, none, required, or a named function. To force a function, use {"type":"function","function":{"name":"get_status"}} for Chat or {"type":"function","name":"get_status"} for Responses. The bridge returns calls; it never executes your functions. Append the assistant call and matching tool result to the next request's history.
• Chat image content uses {"type":"image_url","image_url":{"url":"..."}}; Responses uses {"type":"input_image","image_url":"..."}. URLs can be base64 image data URLs or public HTTPS URLs. Remote-image downloads are limited to 20 MiB and reject private/loopback destinations by default. The total JSON request body is limited to 32 MiB.
• Set Chat reasoning_effort or Responses reasoning.effort to low, medium, or high. A model suffix such as gemini-flash@think=high is also accepted; an explicit body setting takes precedence.
• The configured default thinking effort is low for reasoning-capable models. Disabling-style values map to low; they do not disable Gemini's thinking entirely.
• BRIDGE_LIVE_THOUGHTS=false suppresses separately extracted reasoning output; it does not change the upstream thinking level or guarantee removal of every model-written reasoning passage from ordinary answer text.
• When tools are enabled, prose answers longer than 320 bytes stream live instead of being held for the full turn; mid-answer tool envelopes and fenced envelope look-alikes inside plain prose stay out of the streamed prefix until parsing commits the turn. Envelope mentions quoted as documentation pass through as text and never error as malformed calls.
• The thinking-effort config maps only low, medium, and high; an explicit BRIDGE_DEFAULT_THINKING=medium in the environment or an explicit body effort raises the built-in low default for that deployment or request.

All /v1/* endpoints below use the same authentication resolver. Account keys scope models, accounts, and quota to their account; session status and refresh are not restricted to an admin-only API.

/v1/refresh rejects requests carrying an Origin header. Model names and quota information come from Gemini Web and can change independently of this repository.

The daemon listens on loopback by default. BRIDGE_API_KEY defaults to public, and unauthenticated access is allowed in that mode.

Two kinds of key exist, and they do different things:

Use the pool key unless you specifically need to pin an account. Pool routing is described under BRIDGE_ACCOUNT_STRATEGY below.

• BRIDGE_API_KEY=public means the pool key is public and requests without a key are accepted. Set BRIDGE_API_KEY to a random value before exposing the daemon beyond loopback; the account keys then keep working alongside it.
• Account keys are registered for every loaded account file. They are predictable from the filename, so treat them as routing aliases, not secrets. Setting a pool key does not remove them.
• BRIDGE_ACCOUNT_TOKENS adds token:account_id mappings for custom account keys. It does not disable the automatically registered aliases.
• Authorization: Bearer <key> is recommended. x-api-key, x-goog-api-key, and ?key= are also accepted; query keys can leak into URL logs.
• The daemon serves plain HTTP, not HTTPS. For access outside the local machine, use a private network/tunnel or an authenticated TLS reverse proxy that restricts access independently of the daemon's routing keys. Do not publish the port directly to an untrusted network.
• Startup warns about a non-loopback bind with default authentication; it does not refuse to start. /health remains unauthenticated even when a pool key is set.

Account files contain Google session credentials and are written with mode 0600 on POSIX systems. The session cache also contains sensitive continuation metadata. Protect the whole data directory with OS permissions, exclude it from version control and shared backups, and do not paste cookies or account responses into issues. On Windows, use appropriate filesystem ACLs rather than relying on POSIX mode bits.

Set environment variables before starting ./gsb. The binary reads HOST and PORT, not BRIDGE_HOST or BRIDGE_PORT.

All three strategies share the same eligibility rules. An account is skipped when it is quarantined after an upstream restriction, when its cached quota shows the requested model exhausted, when its per-account RPM or concurrency limit is reached, or when it failed within the last 60 seconds. An account that already holds the conversation's continuation cache is preferred, so a multi-turn conversation stays on one Gemini session even when the pool rotates. A failed account is retried after its cooldown instead of being demoted permanently.

rotate is the default because it keeps one Gemini session per conversation and leaves the other accounts at full quota as standby. It does not reclaim an earlier account the moment that account recovers; it continues forward from the current position. Use fill-first when you want a fixed preferred account to take traffic again as soon as it is healthy.

Duration values are in milliseconds.

For example, use an outbound proxy without changing the local API address:

BRIDGE_PROXY_SERVER=socks5://127.0.0.1:1080 ./gsb

BRIDGE_PROXY_SERVER applies to Gemini transport, not the separate remote-image downloader. It does not provide a process-wide proxy or privacy boundary. WEB_CRED_FILE is parsed by configuration but is not used by the daemon's credential loader; use $BRIDGE_HOME/accounts/ for account management.

./gsb --help
./gsb --probe
./gsb --rotate
curl -sS http://127.0.0.1:20133/health
curl -sS http://127.0.0.1:20133/v1/quota \
  -H 'Authorization: Bearer gsb-acc1'
curl -sS -X POST http://127.0.0.1:20133/v1/refresh \
  -H 'Authorization: Bearer gsb-acc1'

--accounts prints one row per loaded account with a computed status, so you can see at a glance which accounts are usable without calling /v1/accounts and interpreting raw fields:

./gsb --accounts              # read the saved account files
./gsb --accounts --accounts-live   # query upstream for fresh models and quota first

--probe bootstraps configured accounts and prints model/quota details; inspect per-account errors, not just the command's exit status. --rotate attempts cookie renewal, but cannot restore a revoked Google session. Re-import credentials when sign-in is required.

Run ./gsb directly for predictable environment handling. The optional Bash helper ./start.sh builds a missing or outdated binary when a Go toolchain is available (or runs the existing binary if not) and starts the daemon.

For a pool-key request, a 429 may say that no pool account can serve the requested model and summarize unavailable accounts by reason (exhausted, cooling, rate_limited, or busy). The message intentionally reports counts rather than emails or credentials; use /v1/accounts?live=1 for per-account detail. An account-specific quota message is preserved for account-key requests.

Quota-related errors may include Retry-After and X-Resets-At when usable reset information is available. When an error is caused by a silent model downgrade rather than an upstream quota timer, gsb uses a short retry cooldown and includes X-GSB-Retry-Reason so clients can tell the difference. SSE requests can emit an error after HTTP headers have been sent; clients must inspect stream events, not only the HTTP status.

flowchart LR
    C[OpenAI-compatible client] -->|Chat Completions or Responses| B[gsb API bridge]
    B -->|Authenticated web requests| G[Gemini Web]
    G -->|Generation frames| B
    B -->|JSON or SSE| C

The request path has four parts:

1. Resolve the caller's account scope and requested model, then check tool contracts and known quota state.
2. Normalize conversation history, images, thinking effort, and tools. Reuse cached Gemini continuation metadata where possible; upload older history as text attachments when necessary.
3. Send requests using a per-account uTLS/HTTP2 transport. The default Chrome_150_PSK profile and ordered headers replace a headless browser process; they do not emulate every property of a real browser.
4. Parse Gemini's generation frames, separate available reasoning and tool calls, validate the result, and return the selected OpenAI-compatible response format.

Background workers refresh model/quota information, rotate cookies, and retire idle sessions. Updated cookies are persisted to account files, and continuation metadata is stored in $BRIDGE_HOME/session-cache.json.

AGENTS.md records the setup rules for AI coding agents. Its main point: connect an account with gsb --login, and treat cookie import as a fallback for browser profiles that are already signed in.

Build and run the existing checks from the repository root:

go build -o gsb ./cmd/gsb
go vet ./...
go test -race ./...

When reporting a bug, include the endpoint, model ID, HTTP/error code, OS, Go version, and redacted daemon logs. Remove cookies, API keys, email addresses, prompts, and tool outputs containing private data.

MIT.