Skip to content

Gemini CLI through the Nautili gateway: two environment variables, no new key

Point Gemini CLI at the gateway's native Gemini listener in Login with Google or API-key mode, send one prompt, and find it under Seats or Traces.

10 min read

What you’ll have at the end

By the end, every prompt you type into Gemini CLI goes through your Nautili gateway and shows up in the dashboard, with nothing changed on the Google side. Your Google login or Gemini API key keeps paying. The gateway observes, records tokens and cost, and forwards your credential byte for byte.

Last reviewed: November 6, 2026. Login with Google bootstrap exercised end to end through a local gateway on November 6, 2026 (gateway forwarded, Google refused the individual account). Verified against the gateway on devzero-inc/nautir main (gateway/gateway/surface_gemini.go, gateway/config/config.go) and Gemini CLI main (packages/core/src/code_assist/server.ts, packages/core/src/core/contentGenerator.ts).

This is the coding-tools track: passthrough traffic on your own subscription or key, not the keyed sk-dz- path. You get telemetry and attribution. You do not get routing profiles or guardrail enforcement on this traffic, because those need an issued key, and Gemini CLI sends a Google credential.

How it works

The gateway runs a native Gemini listener next to the OpenAI-compatible, Anthropic and OpenAI/Codex ones. It speaks the Gemini wire exactly as Google does:

Gemini CLI modeLogin with Google (Standard or Enterprise licence only, see below)What the CLI callsPOST /v1internal:generateContent, :streamGenerateContent, plus the loadCodeAssist and onboardUser bootstrap calls at startupWhere the gateway forwards itGoogle's Code Assist API, on your OAuth token
Gemini CLI modeGemini API key (AI Studio)What the CLI callsPOST /v1beta/models/{model}:generateContent, :streamGenerateContent?alt=sse, GET /v1beta/modelsWhere the gateway forwards itGoogle AI Studio, on your GEMINI_API_KEY

The listener tells the two apart by the credential. A Bearer OAuth token goes to Code Assist; an x-goog-api-key header or ?key= query goes to AI Studio. One address serves both modes, so you set the same gateway host in either case. Vertex AI mode is not covered by this listener.

Gemini CLI has one override per mode, read from the environment:

ModeLogin with GoogleVariableCODE_ASSIST_ENDPOINTDefault the CLI useshttps://cloudcode-pa.googleapis.com
ModeGemini API keyVariableGOOGLE_GEMINI_BASE_URLDefault the CLI useshttps://generativelanguage.googleapis.com

You set the one for the mode you use. Setting both is harmless.

Before you begin

  • A Proxy Gateway, self-hosted or DevZero-hosted. The Shared Gateway serves sk-dz- keys only and has no Gemini listener. The listener is on by default on a Proxy Gateway (GEMINI_LISTEN_ADDR, port 8082).
  • Its Gemini address. On a local binary or Docker that is http://localhost:8082. In-cluster it is the gateway service on port 8082. On a hosted gateway, or a self-hosted one with the chart's ingress hostnames on, it is https://gemini-<your-gateway-host>: the chart derives the native hostnames by prefixing your base host, the same way the hosted provisioner does. See Ports.
  • Gemini CLI installed and already working against Google directly. Export GEMINI_API_KEY (or complete the Login with Google flow on a Standard or Enterprise licence) and run gemini once before you add the gateway. That way the only variable when something fails is the base URL.

Step 1: Point the CLI at the gateway

Pick the block for the mode Gemini CLI is using. The address below is the local one; substitute https://gemini-<your-gateway-host> for a hosted gateway.

export CODE_ASSIST_ENDPOINT="http://localhost:8082"
gemini

To make it stick for every session, put the same line in ~/.gemini/.env, which Gemini CLI loads on startup, or in a project's .gemini/.env to scope it to one repository. Shell profiles work too.

No path suffix. The CLI appends its own /v1internal:... or /v1beta/models/... paths, and the gateway forwards them verbatim under the upstream base.

In Login with Google mode the CLI fires loadCodeAssist and onboardUser the moment it starts, before any model is chosen. The gateway admits those without a model and never counts them as inference; they bypass the exact cache and are not billed. If the CLI reaches its prompt, the bootstrap went through the gateway.

Step 2: Send one prompt

Non-interactive is the quickest check. In a directory you have not opened interactively, Gemini CLI refuses to run headless until the workspace is trusted, so pass the trust variable too:

GEMINI_CLI_TRUST_WORKSPACE=true gemini -p "Reply with the single word: gateway"

If the CLI still tries Login with Google, it is honouring the auth type saved in ~/.gemini/settings.json from an earlier session. Set security.auth.selectedType to gemini-api-key there, or pick it from /auth in an interactive session.

Interactive sessions work the same way; every turn is a streamGenerateContent call with alt=sse, which the gateway streams back without buffering.

Model names on this listener are Google's own (gemini-3.8-flash, or whatever GET /v1beta/models lists for your key), not the catalog's author/slug form. That is the passthrough contract: the path reaches Google unchanged, so the CLI's model picker keeps working with no custom model entry.

Step 3: Check it without the CLI

If you want to see the listener on its own, the Gemini wire is a plain POST. This is API-key mode:

curl -s "http://localhost:8082/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"parts":[{"text":"Reply with the single word: gateway"}]}]}'
{
"candidates": [
{ "content": { "parts": [{ "text": "gateway" }], "role": "model" }, "finishReason": "STOP" }
],
"usageMetadata": { "promptTokenCount": 9, "candidatesTokenCount": 1, "totalTokenCount": 10 }
}

The response is Google's, unchanged in shape. usageMetadata is what the gateway prices the row from. Errors come back unchanged too: a 404 NOT_FOUND naming a retired model (Google no longer serves gemini-2.5-flash to keys created after the 3.x generation shipped) or a 503 UNAVAILABLE for high demand is Google's answer, forwarded as is, and the gateway records the row with that status.

Verify in the dashboard

Where the traffic lands depends on the mode, because the two modes are two billing regimes:

  • Login with Google is a subscription seat. Open Seats. The gateway tags the seat vendor as gemini, and the screen shows active seats, requests, tokens and an API-equivalent value: what the same traffic would have cost on the metered API. That figure is informational capacity, never savings, because a flat seat fee moves nothing when traffic drops.
  • Gemini API key is metered traffic on your own key. Open Traces under Usage; each call is a row with model, status, tokens and catalog-priced cost, and the AI spend screen counts it under Your provider keys (BYOK).

Two things differ from the keyed quickstart, and both have a fix.

Sessions. In Login with Google mode the CLI puts its own session_id inside the Code Assist envelope, but the gateway does not read it, and the AI Studio wire has no session field at all. Without a session header the gateway falls back to its inferred session: an id derived from your credential, the system prompt and a time bucket, which is good enough to group the turns of one conversation but is not stable across a long day. To pin sessions explicitly, send X-Dz-Session-Id yourself.

Attribution. The gateway reads X-Dz-User, X-Dz-Team, X-Dz-Project and X-Dz-Env on this listener exactly as on the keyed ones. Gemini CLI has no settings entry for headers, but it does take them from GEMINI_CLI_CUSTOM_HEADERS, a comma-separated list of Name: value pairs that it attaches in both auth modes:

export GEMINI_CLI_CUSTOM_HEADERS="X-Dz-Project: checkout, X-Dz-Env: dev, X-Dz-Session-Id: $(uuidgen)"

Put a per-project value in that project's .gemini/.env and the rows land under the right project without any change to the gateway. Without it, attribution follows the credential alone.

Troubleshooting

Symptomconnection refused on port 8082CauseYou are on the Shared Gateway, or GEMINI_LISTEN_ADDR is empty on a self-hosted install.FixUse a Proxy Gateway. On self-hosted, set GEMINI_LISTEN_ADDR=:8082 and publish the port.
SymptomThe CLI still talks to Google directlyCauseThe variable is set for the other mode, or in a shell the CLI does not inherit.FixCODE_ASSIST_ENDPOINT only applies to Login with Google; GOOGLE_GEMINI_BASE_URL only to API-key mode. Check gemini reports the auth mode you expect, and put the variable in ~/.gemini/.env.
Symptom401 or 403 from Google, passed throughCauseThe OAuth token expired or the API key is wrong. The gateway forwards your credential as is and does not retry it.FixRun /auth inside the CLI to log in again, or re-export GEMINI_API_KEY.
SymptomFailed to sign in ... no longer supported for Gemini Code Assist for individualsCauseGoogle's June 2026 cutoff for individual, AI Pro and AI Ultra accounts, returned through the gateway unchanged.FixSwitch to API-key mode with GOOGLE_GEMINI_BASE_URL, or sign in on a Code Assist Standard or Enterprise licence.
Symptom400 invalid_model_idCauseThe address points at the OpenAI-compatible listener (8080 or the base host) instead of the Gemini one.FixUse port 8082 or the gemini- hostname. The Gemini listener takes Google's model names unchanged.
Symptom429 or 503 UNAVAILABLE from Google, passed throughCauseYour Google quota or seat rate limit, or Google's own capacity, not a gateway guardrail. Guardrails do not apply to passthrough.FixWait for Google's reset, or move the workload to an issued key on the keyed path.
Symptom404 NOT_FOUND: model no longer available to new usersCauseGoogle retired that model for keys issued after its successor shipped.FixPick a model from GET /v1beta/models on your key, for example gemini-3.8-flash, and set it with gemini -m.
SymptomRows appear but no routing profile or guardrail ranCauseExpected on this track.FixTo get the keyed path, send an sk-dz- key to the OpenAI-compatible listener from an SDK; see API access.

Next steps

Ready to keep going?

Explore the next guide or start routing through Nautili.