Google Gemini

Use Gemini 2.5 Flash, Gemini 3.1 Pro, and other Google models with Docker Agent.

Setup

Docker Agent reads the first credential it finds from these environment variables (see pkg/model/provider/gemini/client.go):

# Gemini Developer API
export GOOGLE_API_KEY="AI..."   # or GEMINI_API_KEY

# Vertex AI (no API key; uses Application Default Credentials)
gcloud auth application-default login
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT="my-gcp-project"
export GOOGLE_CLOUD_LOCATION="us-central1"

Configuration

Inline

agents:
  root:
    model: google/gemini-3.8-flash

Named Model

models:
  gemini:
    provider: google
    model: gemini-3.8-flash
    temperature: 0.5

Available Models

Generated Images

Some Gemini models (e.g. gemini-2.5-flash-image) are designed to generate an image directly as part of their reply, not just describe one. Docker Agent requests that image output on supported Google surfaces — the models gateway, direct Gemini API, and Vertex AI — according to one binding policy: explicit false, explicit true, then an exact models.dev record whose Modalities.Output contains image. An omitted image flag, including output_capabilities: {}, uses that catalogue default. Unknown models or unavailable catalogue data leave image response modalities disabled; model names are never used to guess capability. Each eligible ordinary chat request asks for text and image output. Vertex AI has deterministic guard/predicate coverage; live image-generation validation is deferred.

Docker Agent attempts to save each returned image and display it in the TUI — see Generated Media for file naming, collision handling, and rendering details.

The workspace file is the visible deliverable. After that file and its manifest entry are saved, a portable copy is also stored in the session database and preferred when the session is reopened. It can render the original generated bytes even if the workspace file was edited, moved, or deleted. Generated-media storage and resolution do not impose a size cap. If portable persistence fails, the workspace file is still kept and the turn includes a warning. Sessions created before portable copies were introduced continue to use their manifest-gated workspace files.

models:
  gemini-image:
    provider: google
    model: gemini-2.5-flash-image

When output_capabilities.image is omitted, including in an empty block, Docker Agent uses models.dev output modalities for the exact known model. Set it explicitly for custom models or to override incorrect catalogue data; unknown or unavailable metadata remains disabled and capability is never guessed from the model name.

Session-title and compaction requests omit image response modalities and bypass the guard even for image-output-capable models. They do not explicitly force TEXT-only output. Ordinary image-output requests with custom function tools or structured output are rejected locally before any request is sent. Google Search, Maps, and code-execution built-ins remain available. When custom tools conflict, Docker Agent uses models.dev's tool_call capability to clarify whether the model cannot call tools at all or supports tools only outside an image-output request. Unknown catalogue data keeps the conservative generic message.

A few provider-side behaviors to know:

• The provider decides the image format (typically PNG). Asking for a .gif or .svg filename does not transcode anything — the saved file's extension is corrected to match the data actually returned.
• An image is not guaranteed. Even a correctly configured image model can answer with text only and generate no image. At a text-only stop, phrases such as "generate an image" or "draw a picture" in the last user prompt trigger a nonfatal warning while preserving the reply: The model returned text but no image for this image-generation request. Try rephrasing the request. This phrase-based check is not semantic intent detection and does not check output capability: negated or quoted phrases can match and other wording can be missed. It does not track a whole submission across tool calls, steering, stop hooks, or handoffs. A terminal provider error skips this check, as does structured output configured on the current agent model; per-call overrides and reply content are not independently classified.

Thinking Budget

Gemini supports two approaches depending on the model version:

Gemini 2.5 (Token-based)

models:
  gemini-no-thinking:
    provider: google
    model: gemini-2.5-flash
    thinking_budget: 0 # disable thinking

  gemini-dynamic:
    provider: google
    model: gemini-2.5-flash
    thinking_budget: -1 # dynamic (model decides) — default

  gemini-fixed:
    provider: google
    model: gemini-2.5-flash
    thinking_budget: 8192 # fixed token budget

Gemini 3 (Level-based)

models:
  gemini-pro:
    provider: google
    model: gemini-3.1-pro-preview
    thinking_budget: high # default for Pro: low | high

  gemini-flash:
    provider: google
    model: gemini-3.8-flash
    thinking_budget: medium # default for Flash: minimal | low | medium | high

Built-in Tools (Grounding)

Gemini models support built-in tools that let the model access Google Search and Google Maps directly during generation. Enable them via provider_opts:

models:
  gemini-grounded:
    provider: google
    model: gemini-2.5-flash
    provider_opts:
      google_search: true
      google_maps: true
      code_execution: true

Vertex AI Model Garden

You can use non-Gemini models (e.g. Claude, Llama) hosted on Google Cloud's Vertex AI Model Garden through the google provider. When a publisher is specified in provider_opts, requests are routed through the appropriate Vertex AI endpoint instead of the Gemini SDK:

• Anthropic Claude (publisher: anthropic) uses the Anthropic-native :rawPredict / :streamRawPredict endpoints. Claude models on Vertex AI do not support the OpenAI /chat/completions path.
• Other publishers (e.g. meta, mistral) use Vertex AI's OpenAI-compatible /chat/completions endpoint.

Authentication

Vertex AI uses Google Cloud Application Default Credentials (ADC). Make sure you are authenticated:

gcloud auth application-default login

Configuration

models:
  claude-on-vertex:
    provider: google
    model: claude-sonnet-5
    provider_opts:
      project: my-gcp-project       # GCP project ID (or set GOOGLE_CLOUD_PROJECT)
      location: us-east5             # GCP region (or set GOOGLE_CLOUD_LOCATION)
      publisher: anthropic           # Model publisher (anthropic, meta, etc.)