Learn about configuring Claude Code through Google Cloud's Agent Platform, formerly Vertex AI, including setup, IAM configuration, and troubleshooting.
If you have Google Cloud credentials and want to start using Claude Code through Google Cloud's Agent Platform, the login wizard walks you through it. You complete the GCP-side prerequisites once per project; the wizard handles the Claude Code side.
Start Claude Code and choose Google Cloud's Agent Platform
Run claude. At the login prompt, select 3rd-party platform, then Google Vertex AI, the label the login prompt still uses for Google Cloud's Agent Platform. If you're already signed in, run /login to open the same menu.
3
Follow the wizard prompts
Choose how you authenticate to Google Cloud: Application Default Credentials from gcloud, a service account key file, or credentials already in your environment. The wizard detects your project and region, verifies which Claude models your project can invoke, and lets you pin them. It saves the result to the env block of your user settings file, so you don't need to export environment variables yourself.
After you've signed in, run /setup-vertex any time to reopen the wizard and change your credentials, project, region, or model pins. The model pin step starts from your currently pinned models. The wizard writes to ~/.claude/settings.json, or to $CLAUDE_CONFIG_DIR/settings.json when CLAUDE_CONFIG_DIR is set.
Region configuration
Claude Code supports Google Cloud's Agent Platform global, multi-region, and regional endpoints. Set CLOUD_ML_REGION to global, a multi-region location such as eu or us, or a specific region such as us-east5. Claude Code selects the correct Google Cloud's Agent Platform hostname for each form, including the aiplatform.eu.rep.googleapis.com and aiplatform.us.rep.googleapis.com hosts for multi-region locations.
Set up manually
To configure Google Cloud's Agent Platform through environment variables instead of the wizard, for example in CI or a scripted enterprise rollout, follow the steps below.
1. Enable Agent Platform API
Enable Google Cloud's Agent Platform API in your GCP project. Replace YOUR-PROJECT-ID with your GCP project ID here and in the configuration step below:
# Set your project ID
gcloud config set project YOUR-PROJECT-ID# Enable Agent Platform API
gcloud services enable aiplatform.googleapis.com
2. Request model access
Request access to Claude models in Google Cloud's Agent Platform:
Claude Code v2.1.121 or later supports X.509 certificate-based Workload Identity Federation through the same Application Default Credentials chain. Set GOOGLE_APPLICATION_CREDENTIALS to the path of your credential configuration file.
Advanced credential configuration
Claude Code supports automatic credential refresh for GCP through the gcpAuthRefresh setting. Add it to your Claude Code settings file, for example ~/.claude/settings.json. When Claude Code detects that your GCP credentials are expired or cannot be loaded, it runs the configured command to obtain new credentials before retrying the request.
Claude Code shows you the command's output, but can't send the command interactive input. This works well for browser-based authentication flows where the CLI shows a URL and you complete authentication in the browser. The refresh command times out after three minutes if authentication does not complete. If you set gcpAuthRefresh in project settings such as .claude/settings.json, the command runs only after you accept the workspace trust prompt.
4. Configure Claude Code
Set the following environment variables:
# Enable Agent Platform integrationexport CLAUDE_CODE_USE_VERTEX=1export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID# Optional: Override the Agent Platform endpoint URL for custom endpoints or gateways# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com# Optional: Disable prompt caching if needed# export DISABLE_PROMPT_CACHING=1# Optional: Request 1-hour prompt cache TTL instead of the 5-minute default# export ENABLE_PROMPT_CACHING_1H=1# When CLOUD_ML_REGION=global, override region for models that don't support global endpointsexport VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
Prompt caching is enabled automatically. To disable it, set DISABLE_PROMPT_CACHING=1. To request a 1-hour cache TTL instead of the 5-minute default, set ENABLE_PROMPT_CACHING_1H=1; cache writes with a 1-hour TTL are billed at a higher rate. For heightened rate limits, contact Google Cloud support. When using Google Cloud's Agent Platform, the /logout command is unavailable since authentication is handled through Google Cloud credentials.
Claude Code decides between MCP tool search and upfront loading by model generation:
Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later: Claude Code enables tool search by default.
Earlier models, including all Claude 3.x models: Claude Code loads MCP tool definitions upfront, because their Agent Platform serving stacks reject the required beta header. Setting ENABLE_TOOL_SEARCH=true doesn't override this.
Set ENABLE_TOOL_SEARCH=false to disable tool search on every model. Before v2.1.221, Claude Code disabled tool search for all models on Google Cloud's Agent Platform unless you set ENABLE_TOOL_SEARCH=true.
5. Pin model versions
Set these environment variables to specific Google Cloud's Agent Platform model IDs.
Without ANTHROPIC_DEFAULT_OPUS_MODEL, the opus alias on Google Cloud's Agent Platform resolves to Opus 5, and without ANTHROPIC_DEFAULT_SONNET_MODEL, the sonnet alias resolves to Sonnet 4.5. This example pins each alias to a specific version:
Claude Code uses these default models when no pinning variables are set:
Model type
Default value
Primary model
claude-opus-5
Small/fast model
claude-sonnet-4-5@20250929
Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Google Cloud's Agent Platform, Claude Code uses the default Sonnet model for background tasks because Haiku may not be enabled in every project or region. Two selections change which model carries them:
When you select a primary model with --model, ANTHROPIC_MODEL, or the model setting, background tasks use that model. Setting ANTHROPIC_DEFAULT_OPUS_MODEL without ANTHROPIC_DEFAULT_SONNET_MODEL counts as a selection too, because the built-in Sonnet model may not be enabled in a project that steers its own Opus.
To use Haiku for background tasks, set ANTHROPIC_DEFAULT_HAIKU_MODEL to a model ID that is available in your project.
On v2.1.207 through v2.1.218, the primary model on Google Cloud's Agent Platform defaulted to Opus 4.8 and the opus alias resolved to Opus 4.8. Before v2.1.207, the primary model defaulted to Sonnet 4.5, the opus alias resolved to Opus 4.6, and background tasks always used the primary model.
Start Claude Code and run /status to confirm the setup. The API provider line shows Google Vertex AI, and the GCP project, Default region, and Model lines show your project ID, region, and resolved model. If the provider line is missing, the environment variables aren't reaching the process. Confirm they are exported in the shell where you launched claude, or set them in the env block of your settings file.
Startup model checks
When Claude Code starts with Google Cloud's Agent Platform configured, it verifies that the models it intends to use are accessible in your project.
If you have pinned a model version that is older than the current Claude Code default, and your project can invoke the newer version, Claude Code prompts you to update the pin. Accepting writes the new model ID to your user settings file and restarts Claude Code. Declining is remembered until the next default version change.
If you have not pinned a model and the current default is unavailable in your project, Claude Code falls back for the current session and shows a notice. It tries earlier versions of the default model first and, when the default is an Opus model and no Opus version is available, falls back to the default Sonnet model. The fallback is not persisted. Enable the newer model in Model Garden or pin a version to make the choice permanent.
When you start the session on a specific Sonnet or Opus version, with --model, ANTHROPIC_MODEL, or the model setting, that version acts as the session's pinned default for the matching sonnet or opus alias. Claude Code skips the availability check for the built-in default your model replaces and starts on the model you configured, with no fallback notice.
Model aliases such as opus don't act as pins, and neither does a model ID Claude Code doesn't recognize.
IAM configuration
Assign the required IAM permissions:
The roles/aiplatform.user role includes the required permissions:
aiplatform.endpoints.predict - Required for model invocation and token counting
For more restrictive permissions, create a custom role with only the permissions above.
Claude Sonnet 5, Opus 4.6 and later, and Sonnet 4.6 support the 1M token context window on Google Cloud's Agent Platform. Sonnet 5 always runs with the 1M window, with no [1m] variant to select. For the other models, Claude Code automatically enables the extended context window when you select a 1M model variant.
Verify the model is available in the location you specified. Some models are offered only on global or multi-region locations such as eu and us, not in specific regions
If using CLOUD_ML_REGION=global, check that your models support global endpoints in Model Garden under "Supported features". For models that don't support global endpoints, either:
Specify a supported model via ANTHROPIC_MODEL or ANTHROPIC_DEFAULT_HAIKU_MODEL, or
Set a region or multi-region location using VERTEX_REGION_<MODEL_NAME> environment variables
If you encounter 429 errors:
For regional endpoints, ensure the primary model and small/fast model are supported in your selected region
Consider switching to CLOUD_ML_REGION=global for better availability
199[Prompt caching](/docs/en/prompt-caching) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. For heightened rate limits, contact Google Cloud support. When using Google Cloud's Agent Platform, the `/logout` command is unavailable since authentication is handled through Google Cloud credentials.199[Prompt caching](/docs/en/prompt-caching) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. For heightened rate limits, contact Google Cloud support. When using Google Cloud's Agent Platform, the `/logout` command is unavailable since authentication is handled through Google Cloud credentials.
200200
201Claude Code disables [MCP tool search](/docs/en/mcp#scale-with-mcp-tool-search) by default on Google Cloud's Agent Platform, so MCP tool definitions load upfront. Google Cloud's Agent Platform supports tool search for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later. Set `ENABLE_TOOL_SEARCH=true` to enable it on those models. Earlier models on Google Cloud's Agent Platform do not accept the required beta header, and requests fail if you enabletoolsearchwiththem.201Claude Code decidesbetween [MCP tool search](/docs/en/mcp#scale-with-mcp-tool-search) and upfrontloadingbymodelgeneration:
202
203* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later**: Claude Code enables tool search by default.
204* **Earlier models, including all Claude 3.x models**: Claude Code loads MCP tool definitions upfront, because their Agent Platform serving stacks reject the required beta header. Setting `ENABLE_TOOL_SEARCH=true` doesn't override this.
205
206Set `ENABLE_TOOL_SEARCH=false` to disable tool search on every model. Before v2.1.221, Claude Code disabled tool search for all models on Google Cloud's Agent Platform unless you set `ENABLE_TOOL_SEARCH=true`.
202207
203### 5. Pin model versions208### 5. Pin model versions
204209
234 Opus models have a higher per-token price than Sonnet models, so a deployment that doesn't pin a primary model is billed at the Opus rate once it updates to v2.1.207 or later. To keep Sonnet 4.5 as the primary model, set `ANTHROPIC_MODEL` to its full model ID. A deployment that steers the default with `ANTHROPIC_DEFAULT_SONNET_MODEL` and doesn't set `ANTHROPIC_DEFAULT_OPUS_MODEL` keeps its steered Sonnet model as the default.239 Opus models have a higher per-token price than Sonnet models, so a deployment that doesn't pin a primary model is billed at the Opus rate once it updates to v2.1.207 or later. To keep Sonnet 4.5 as the primary model, set `ANTHROPIC_MODEL` to its full model ID. A deployment that steers the default with `ANTHROPIC_DEFAULT_SONNET_MODEL` and doesn't set `ANTHROPIC_DEFAULT_OPUS_MODEL` keeps its steered Sonnet model as the default.
235</Warning>240</Warning>
236241
237{/* min-version: 2.1.219 */}On v2.1.207 through v2.1.218, the primary model on Google Cloud's Agent Platform defaulted to Opus 4.8 and the `opus` alias resolved to Opus 4.8. {/* min-version: 2.1.207 */}Before v2.1.207, the primary model defaulted to Sonnet 4.5, the `opus` alias resolved to Opus 4.6, and background tasks always used the primary model.242On v2.1.207 through v2.1.218, the primary model on Google Cloud's Agent Platform defaulted to Opus 4.8 and the `opus` alias resolved to Opus 4.8. Before v2.1.207, the primary model defaulted to Sonnet 4.5, the `opus` alias resolved to Opus 4.6, and background tasks always used the primary model.
256If you have not pinned a model and the current default is unavailable in your project, Claude Code falls back for the current session and shows a notice. It tries earlier versions of the default model first and, when the default is an Opus model and no Opus version is available, falls back to the default Sonnet model. The fallback is not persisted. Enable the newer model in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) or [pin a version](#5-pin-model-versions) to make the choice permanent.261If you have not pinned a model and the current default is unavailable in your project, Claude Code falls back for the current session and shows a notice. It tries earlier versions of the default model first and, when the default is an Opus model and no Opus version is available, falls back to the default Sonnet model. The fallback is not persisted. Enable the newer model in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) or [pin a version](#5-pin-model-versions) to make the choice permanent.
257262
258{/* min-version: 2.1.211 */}When you start the session on a specific Sonnet or Opus version, with `--model`, `ANTHROPIC_MODEL`, or the [`model` setting](/docs/en/settings), that version acts as the session's pinned default for the matching `sonnet` or `opus` alias. Claude Code skips the availability check for the built-in default your model replaces and starts on the model you configured, with no fallback notice.263When you start the session on a specific Sonnet or Opus version, with `--model`, `ANTHROPIC_MODEL`, or the [`model` setting](/docs/en/settings), that version acts as the session's pinned default for the matching `sonnet` or `opus` alias. Claude Code skips the availability check for the built-in default your model replaces and starts on the model you configured, with no fallback notice.
259264
260Model aliases such as `opus` don't act as pins, and neither does a model ID Claude Code doesn't recognize.265Model aliases such as `opus` don't act as pins, and neither does a model ID Claude Code doesn't recognize.
