Skip to main content

​
Prerequisites

Before configuring Claude Code with Google Cloud’s Agent Platform, formerly Vertex AI, ensure you have:
  • A Google Cloud Platform (GCP) account with billing enabled
  • A GCP project with Google Cloud’s Agent Platform API enabled
  • Access to desired Claude models (for example, Claude Sonnet 4.6)
  • Google Cloud SDK (gcloud) installed and configured
  • Quota allocated in desired GCP region
To sign in with your own Google Cloud’s Agent Platform credentials, follow Sign in with Google Cloud’s Agent Platform below. To deploy Claude Code across a team, use the manual setup steps and pin your model versions before rolling out.

​
Sign in with Agent Platform

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.
1

Enable Claude models in your GCP project

Enable Google Cloud’s Agent Platform API for your project, then request access to the Claude models you want in the Google Cloud’s Agent Platform Model Garden. See IAM configuration for the permissions your account needs.
2

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.
Google Cloud’s Agent Platform may not support the Claude Code default models on every endpoint type. Model availability varies across specific regions, multi-region locations, and global endpoints. You may need to switch to a supported location or specify a supported model.

​
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:

​
2. Request model access

Request access to Claude models in Google Cloud’s Agent Platform:
  1. Navigate to the Google Cloud’s Agent Platform Model Garden
  2. Search for “Claude” models
  3. Request access to desired Claude models (for example, Claude Sonnet 4.6)
  4. Wait for approval (may take 24-48 hours)

​
3. Configure GCP credentials

Claude Code uses standard Google Cloud authentication. For more information, see Google Cloud authentication documentation. Claude Code 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.
Claude Code uses ANTHROPIC_VERTEX_PROJECT_ID as the project ID for Google Cloud’s Agent Platform requests. The GCLOUD_PROJECT and GOOGLE_CLOUD_PROJECT environment variables and the credential file referenced by GOOGLE_APPLICATION_CREDENTIALS take precedence over it. If none of these are set, the project ID is resolved from your gcloud configuration or the attached service account.

​
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, Claude Code runs it under the same workspace trust rule as hooks in settings files, which includes -p sessions in folders you’ve never trusted.

​
4. Configure Claude Code

Set the following environment variables: