​
Prerequisites

Before configuring Claude Code with Vertex AI, ensure you have:

  • A Google Cloud Platform (GCP) account with billing enabled
  • A GCP project with Vertex AI API enabled
  • Access to desired Claude models (e.g., Claude Sonnet 4)
  • Google Cloud SDK (gcloud) installed and configured
  • Quota allocated in desired GCP region

Vertex AI may not support the Claude Code default models on non-us-east5 regions. Ensure you are using us-east5 and have quota allocated, or switch to supported models.

​
Setup

​
1. Enable Vertex AI API

Enable the Vertex AI API in your GCP project:

# Set your project ID
gcloud config set project YOUR-PROJECT-ID

# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

​
2. Request model access

Request access to Claude models in Vertex AI:

  1. Navigate to the Vertex AI Model Garden
  2. Search for “Claude” models
  3. Request access to desired Claude models (e.g., Claude Sonnet 4)
  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.

​
4. Configure Claude Code

Set the following environment variables:

# Enable Vertex AI integration
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optional: Disable prompt caching if needed
export DISABLE_PROMPT_CACHING=1

# Optional: Override regions for specific models
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-central1
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west4
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5

Prompt caching is automatically supported when you specify the cache_control ephemeral flag. To disable it, set DISABLE_PROMPT_CACHING=1. For heightened rate limits, contact Google Cloud support.

When using Vertex AI, the /login and /logout commands are disabled since authentication is handled through Google Cloud credentials.

​
5. Model configuration

Claude Code uses these default models for Vertex AI:

Model typeDefault value
Primary modelclaude-sonnet-4@20250514
Small/fast modelclaude-3-5-haiku@20241022

To customize models:

export ANTHROPIC_MODEL='claude-opus-4@20250514'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

​
IAM configuration

Assign the required IAM permissions:

The roles/aiplatform.user role includes the required permissions:

  • aiplatform.endpoints.predict - Required for model invocation
  • aiplatform.endpoints.computeTokens - Required for token counting

For more restrictive permissions, create a custom role with only the permissions above.

For details, see Vertex IAM documentation.

We recommend creating a dedicated GCP project for Claude Code to simplify cost tracking and access control.

​
Troubleshooting

If you encounter quota issues:

  • Check current quotas or request quota increase through Cloud Console

If you encounter “model not found” 404 errors:

  • Verify you have access to the specified region
  • Confirm model is Enabled in Model Garden

If you encounter 429 errors:

  • Ensure the primary model and small/fast model are supported in your selected region

​
Additional resources