Using Claude Code via Vertex AI | GCP Authentication and Configuration

Benefits of Using Claude Code via Vertex AI

The biggest advantage is that you can run Claude Code using your existing Google Cloud credits or GCP billing account without a separate contract with Anthropic.

For organizations already using a GCP organization account, all cost aggregation, access control, and audit logging for Claude Code can be handled entirely within GCP. In regulated industries such as finance and healthcare, the ability to run Claude Code within VPC Service Controls boundaries is often a key reason for adoption.

Prerequisites | GCP Project and API Setup

To run Claude Code on Vertex AI, prepare the following in advance:

• A GCP account with billing enabled
• A GCP project with the Vertex AI API enabled
• Access to Claude models requested via Vertex AI Model Garden
• Google Cloud SDK (gcloud) installed and initialized
• Quota allocated for the region you intend to use

GCP Pre-configuration Steps

1. Create or select a GCP project and set it as the default project

gcloud config set project YOUR-PROJECT-ID

2. Enable the Vertex AI API

gcloud services enable aiplatform.googleapis.com

3. In Vertex AI Model Garden, search for "Claude," click "Enable" on the model you want to use (e.g., Claude Sonnet 4.6), and request access. Approval may take 24–48 hours.

Quickest Setup Using the Wizard (Recommended)

From Claude Code v2.1.98 onward, the /setup-vertex command launches an interactive wizard. Since it completes the configuration without requiring you to manually write environment variables, the wizard is recommended for both individual and team use.

1. Check your Claude Code version

claude --version
# v2.1.98 or later is required

2. Run claude and open the login prompt
3. Select "3rd-party platform" → "Google Vertex AI"
4. Choose your authentication method for Google Cloud:
   • Application Default Credentials obtained via gcloud auth application-default login
   • A service account key file
   • Credentials already present in your environment
5. The wizard auto-detects your project and region, verifies the enabled Claude models, and pins them
6. The configuration is automatically saved to the env block in your user settings file

You can re-run /setup-vertex at any time to change credentials, project, region, or model after the initial setup.

Manual Configuration via Environment Variables

For CI/CD pipelines or bulk deployment to teams, setting environment variables directly is the appropriate approach.

# Enable Vertex AI integration
export CLAUDE_CODE_USE_VERTEX=1

# Use the global endpoint (recommended for most cases)
export CLOUD_ML_REGION=global

# GCP project ID
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

For CLOUD_ML_REGION, you can set global (global endpoint), eu / us (multi-region), or a specific region such as us-east5. Note that not all models support the global endpoint — check the Vertex AI Model Garden before proceeding.

To override the region on a per-model basis, use the dedicated environment variables:

# Per-model region override for models not supported on the global endpoint
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

Configuring Automatic Credential Refresh

To automatically refresh credentials when they expire, use the gcpAuthRefresh setting in your configuration file:

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

The specified command is executed when Claude Code detects an authentication error and times out after 3 minutes. It supports flows that require opening a URL in a browser to complete authentication. This setting can also be written in the project settings file (.claude/settings.json) and is only executed after workspace trust has been accepted.

Configuring IAM Permissions

The GCP permission required for Claude Code is the roles/aiplatform.user role. The key permission included in this role is:

• aiplatform.endpoints.predict — required for model calls and token counting

If you want to apply least-privilege access, you can create a custom role containing only aiplatform.endpoints.predict. Grant the role with the following command:

gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
  --member="user:YOUR_EMAIL@example.com" \
  --role="roles/aiplatform.user"

For detailed access control policies, refer to the Vertex IAM documentation. The official recommendation is to create a dedicated GCP project for Claude Code to simplify cost tracking and access control.

Pinning Model Versions

When distributing Claude Code to multiple users, it is important to explicitly pin the model version. Without pinning, aliases such as sonnet or opus resolve to the latest version — which may not yet be enabled in your Vertex AI project, causing startup errors.

# Pin to a specific model version
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

Current and past model version IDs can be found in the Anthropic model overview.

If an unpinned model is unavailable, Claude Code automatically falls back to the previous version and displays a notification. Since the fallback is temporary, a permanent fix requires either enabling the model in Model Garden or configuring a pin.

To use the 1 million token context window, append [1m] to the model ID. Claude Opus 4.6 and later, as well as Sonnet 4.6, support 1M context on Vertex AI. This option is also available in the wizard's pinning settings.

Region Configuration and Global Endpoint

Vertex AI provides endpoints at three levels: specific region, multi-region, and global.

When accessing from Japan, global or us-east5 are the first options to try. The Tokyo region (asia-northeast1) has had periods where Claude models were not directly available, so check the Vertex AI partner model availability by region regularly.

If you use CLOUD_ML_REGION=global with a model that does not support the global endpoint, you can make it work by setting per-model region override variables (VERTEX_REGION_CLAUDE_*).

Troubleshooting

Common errors and how to resolve them:

"Could not load the default credentials" error

1. Run gcloud auth application-default login to refresh Application Default Credentials
2. Set GOOGLE_APPLICATION_CREDENTIALS to the path of your service account key file

404 "Model not found" error

1. Verify the model is enabled in Model Garden
2. Check that the model is available in the specified region
3. When using CLOUD_ML_REGION=global, specify a per-model region with VERTEX_REGION_<MODEL_NAME> for models that do not support the global endpoint

429 Rate limit error

1. Verify that both your primary model and Haiku are supported in the selected region
2. Consider switching from a regional endpoint to CLOUD_ML_REGION=global
3. Request a quota increase from the Cloud Console quota management page

Quota issues

Immediately after creating a project, per-region quotas are set low. You can request an increase from the Cloud Console quota page.

Summary

To use Claude Code via Vertex AI, enable the Vertex AI API in your GCP project, request access to models in Model Garden, then enable the integration using the /setup-vertex wizard or by setting the environment variable CLAUDE_CODE_USE_VERTEX=1.

Because GCP cost management, IAM, and security boundaries can be applied directly to Claude Code, this is the ideal configuration for organizations that already have development infrastructure on Google Cloud. When deploying to multiple users, remember to pin the model version. For the latest configuration information, check the official Anthropic documentation, which is updated regularly.