​
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
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west4
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-1@20250805'
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