Claude Code with Google Vertex AI

Vertex AI is Google's managed service for foundation models. You can configure Claude Code to route requests through Vertex AI instead of the direct Anthropic API. This is useful for organizations already invested in Google Cloud, and for enterprise features like IAM controls, monitoring, and cost tracking.

Prerequisites

Before configuring Claude Code with Vertex AI:

Google Cloud Platform (GCP) account with billing enabled
GCP project with Vertex AI API enabled
Access to Claude models in at least one region (requires approval process)
Google Cloud SDK (gcloud) installed and configured
Quota allocated in your desired region(s)

Step 1: Prepare Your GCP Project

1.1 Enable Vertex AI API

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

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

1.2 Request Model Access

Go to Vertex AI Model Garden
Search for "Claude"
Click "Request Access" on your desired Claude model (e.g., Claude Sonnet 4.6)
Wait for approval (usually 24-48 hours)

Tip: You'll see a green checkmark next to the model name once enabled.

Step 2: Configure GCP Authentication

Claude Code uses standard Google Cloud authentication. You have several options:

# Browser-based login
gcloud auth application-default login

# Follow the browser dialog and authorize

This saves credentials to ~/.config/gcloud/application_default_credentials.json.

Option B: Service Account (for servers/automation)

For Claude Code running on a server:

Go to GCP Service Accounts
Create a new service account
Create a JSON key
Store it securely (e.g., in a vault)
Set the environment variable:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Option C: Workload Identity (Kubernetes)

For Claude Code running in GKE:

# Bind Kubernetes Service Account to GCP Service Account
gcloud iam service-accounts add-iam-policy-binding [email protected] \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:YOUR-PROJECT.svc.id.goog[NAMESPACE/KSA-NAME]"

# Claude Code pods automatically use this identity

Workload Identity Documentation

Step 3: Enable Claude Code for Vertex AI

Set these environment variables:

# Enable Vertex AI
export CLAUDE_CODE_USE_VERTEX=1

# GCP Project ID
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

# Region (global or regional)
export CLOUD_ML_REGION=global

# Optional: Disable Prompt Caching if needed
export DISABLE_PROMPT_CACHING=1

Important:

ANTHROPIC_VERTEX_PROJECT_ID is used for model resolution
CLOUD_ML_REGION=global uses Google's global endpoints (best availability)
If global doesn't work, try a specific region (e.g., us-central1)

Step 4: Configure Regions

Global Endpoint (Recommended)

If your models support the global endpoint:

export CLOUD_ML_REGION=global

Advantages: Automatic routing to best region, higher availability

Limitation: Not all models support global endpoints

Regional Endpoints (Fallback)

If global doesn't work, specify a region:

export CLOUD_ML_REGION=us-central1
# or: export CLOUD_ML_REGION=europe-west1
# or: export CLOUD_ML_REGION=asia-southeast1

Vertex AI Regions

Region Override per Model

Use global but fallback to regional for unsupported models:

export CLOUD_ML_REGION=global

# Override for models not in global
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1

Claude Code tries global first, then falls back to these regions.

Step 5: Pin Model Versions

WARNING: Using model aliases without pinning can cause failures when Anthropic releases new models not yet available in your project.

Solution: Always pin specific model IDs:

# Pin Vertex AI model IDs
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

Default Models (without pinning – not recommended for production)

Model Type	Default ID
Primary Model	`claude-sonnet-4-6`
Small/Fast Model (Haiku)	`claude-haiku-4-5@20251001`

Step 6: Configure IAM Permissions

Assign these IAM permissions:

Simplest Option: `roles/aiplatform.user`

This role includes required permissions:

aiplatform.endpoints.predict – Model invocation

# Grant role to user/service account
gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
  --member="user:[email protected]" \
  --role="roles/aiplatform.user"

Strict Option: Custom Role

For minimal permissions:

{
  "title": "Claude Code Vertex AI User",
  "description": "Minimal permissions for Claude Code on Vertex AI",
  "includedPermissions": [
    "aiplatform.endpoints.predict"
  ]
}

Vertex AI IAM Documentation

For Service Accounts

gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
  --member="serviceAccount:[email protected]" \
  --role="roles/aiplatform.user"

Step 7: Enable Prompt Caching (Optional)

Claude Opus 4.6, Sonnet 4.6, Sonnet 4.5, and Sonnet 4 support 1M token context window on Vertex AI.

Claude Code automatically enables extended context for 1M models.

To enable 1M context: Append [1m] to model ID:

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6[1m]'

Prompt caching is automatically enabled. To disable:

export DISABLE_PROMPT_CACHING=1

Note: Contact Google Cloud support for higher rate limits if needed.

Deploying for Multiple Users

1. Create a Dedicated GCP Project

Create a separate project for Claude Code:

Simpler cost tracking
Better access control
Isolated audit logs

2. Model Version Overrides

To offer multiple Claude versions:

{
  "modelOverrides": {
    "claude-opus-4-6": "claude-opus-4-6",
    "claude-opus-4-5-20251101": "claude-opus-4-5-20251101"
  }
}

Users can select versions with /model.

3. Centralized Settings File

Create a settings file (e.g., /opt/claude-code-settings.json):

export CLAUDE_CODE_SETTINGS=/opt/claude-code-settings.json

Include:

Vertex AI configuration
Model pinning
GCP project ID
Region settings
Custom headers

Troubleshooting

Problem: "Model not found" 404

Cause 1: Model not enabled in your project

Solution:

# Go to Model Garden
# https://console.cloud.google.com/vertex-ai/model-garden
# Request access and wait 24-48 hours

Cause 2: Model not available in your region

Solution:

# Check model availability
gcloud ai models describe "claude-sonnet-4-6" --region=us-central1

# Use a different region
export CLOUD_ML_REGION=europe-west1

Problem: "Quota exceeded" or "429 Too Many Requests"

Cause: Project quota exhausted

Solution:

# Check current quotas
gcloud compute project-info describe --project=YOUR-PROJECT-ID

# Request quota increase
# Go to: https://console.cloud.google.com/iam-admin/quotas

For regional issues: Use CLOUD_ML_REGION=global for better load balancing.

Problem: "Model is not enabled in Model Garden"

Cause: Model only shows "Request Access", not enabled yet

Solution:

Go to Model Garden
Look for green checkmark (enabled) vs "Request Access"
If requesting: Wait 24-48 hours for approval

Problem: "Global endpoint not supported for this model"

Cause: Model doesn't support global endpoint

Solution:

# Use region override
export CLOUD_ML_REGION=global
export VERTEX_REGION_CLAUDE_HAIKU=us-east5

Or use regional only:

export CLOUD_ML_REGION=us-central1

Performance & Cost

Prompt Caching

Claude Code automatically uses Vertex AI Prompt Caching with the cache_control flag. This saves 90% on cached token costs.

If problems: Disable with DISABLE_PROMPT_CACHING=1

Cost Comparison: Vertex AI vs Direct API

Scenario	Vertex AI	Direct API
Small orgs (<50 users)	Similar/slightly more (GCP overhead)	Cheaper
Large orgs (>500 users)	Volume discounts available	More expensive
Enterprise & Compliance	Better (IAM, VPC, Audit)	Difficult
Prompt Caching	Massive savings (90% discount)	Standard pricing

Vertex AI Pricing Calculator

Cost Optimization

# 1. Prompt Caching (enabled by default, saves 90%)
# No additional configuration needed

# 2. Use Haiku for simple tasks (5-10x cheaper)
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

# 3. Use Batch API for non-realtime requests
# (70% discount, but hours latency)

Security & Compliance

Data Protection

Vertex AI uses GCP IAM for access control
Optional VPC Service Controls for private connectivity
Data encrypted in transit (TLS) and at rest

Audit Logging

# Cloud Audit Logs show all Vertex AI API calls
gcloud logging read "resource.type=aiplatform.googleapis.com" \
  --limit 10 \
  --project=YOUR-PROJECT-ID

Compliance Certifications

HIPAA: Vertex AI is HIPAA-certified (US regions only)
FedRAMP: Moderately authorized
SOC 2: Type II certified
GDPR: EU data residency available (europe-west1)
EU AI Act: Google provides provider documentation (your responsibility as deployer remains)

Best Practices

Always pin model versions – Aliases can break on new releases
Use global endpoint – Better availability and load balancing
Enable Cloud Logging – Audit trail for compliance
Keep IAM minimal – Use roles/aiplatform.user, not Admin
Enable Prompt Caching – 90% cost savings
Check quotas regularly – Can be exhausted quickly
Use region diversity – Fallback if one region fails
Maintain documentation – Which systems, what data, compliance needs

Prerequisites

Step 1: Prepare Your GCP Project

1.1 Enable Vertex AI API

1.2 Request Model Access

Step 2: Configure GCP Authentication

Option A: gcloud CLI Login

Option B: Service Account (for servers/automation)

Option C: Workload Identity (Kubernetes)

Step 3: Enable Claude Code for Vertex AI

Step 4: Configure Regions

Global Endpoint (Recommended)

Regional Endpoints (Fallback)

Region Override per Model

Step 5: Pin Model Versions

Default Models (without pinning – not recommended for production)

Step 6: Configure IAM Permissions

Simplest Option: roles/aiplatform.user

Strict Option: Custom Role

For Service Accounts

Step 7: Enable Prompt Caching (Optional)

Deploying for Multiple Users

1. Create a Dedicated GCP Project

2. Model Version Overrides

3. Centralized Settings File

Troubleshooting

Problem: "Model not found" 404

Problem: "Quota exceeded" or "429 Too Many Requests"

Problem: "Model is not enabled in Model Garden"

Problem: "Global endpoint not supported for this model"

Performance & Cost

Prompt Caching

Cost Comparison: Vertex AI vs Direct API

Cost Optimization

Security & Compliance

Data Protection

Audit Logging

Compliance Certifications

Best Practices

Additional Resources

Sources and Links

Continue the learning path

Simplest Option: `roles/aiplatform.user`