Skillintermediate

Claude Code on Google Vertex AI

> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further.

Claude Code Knowledge Pack7/10/2026

Overview

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Claude Code on Google Vertex AI

Learn about configuring Claude Code through Google Vertex AI, including setup, IAM configuration, and troubleshooting.

const VID_KEY = 'exp_vid'; const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']); const fnv1a = s => { let h = 0x811c9dc5; for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24); } return h >>> 0; }; const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment'; const [decision] = useState(() => { const params = new URLSearchParams(location.search); const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')]; const force = params.get('gb-force'); if (force) { for (const p of force.split(',')) { const [k, v] = p.split(':'); if (k === flag) return { variant: v || 'treatment', track: false }; } } if (navigator.globalPrivacyControl) { return { variant: 'control', track: false }; } const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/); if (prefsMatch) { try { if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) { return { variant: 'control', track: false }; } } catch { return { variant: 'control', track: false }; } } else { const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1]; if (!country || CONSENT_COUNTRIES.has(country)) { return { variant: 'control', track: false }; } } let vid; try { const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/); if (ajsMatch) { vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, ''); } else { vid = localStorage.getItem(VID_KEY); if (!vid) { vid = crypto.randomUUID(); } document.cookie = ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000; } try { localStorage.setItem(VID_KEY, vid); } catch {} } catch { return { variant: 'control', track: false }; } const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid); return { variant, track: true, vid }; }); useEffect(() => { if (!decision.track) return; fetch('https://api.anthropic.com/api/event_logging/v2/batch', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-service-name': 'claude_code_docs' }, body: JSON.stringify({ events: [{ event_type: 'GrowthbookExperimentEvent', event_data: { device_id: decision.vid, anonymous_id: decision.vid, timestamp: new Date().toISOString(), experiment_id: flag, variation_id: decision.variant === 'treatment' ? 1 : 0, environment: 'production' } }] }), keepalive: true }).catch(() => {}); }, []); return decision.variant === 'treatment' ? treatment : children; };

} />

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 (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 Vertex AI credentials, follow Sign in with Vertex AI below. To deploy Claude Code across a team, use the manual setup steps and pin your model versions before rolling out.

Sign in with Vertex AI

If you have Google Cloud credentials and want to start using Claude Code through Vertex AI, the login wizard walks you through it. You complete the GCP-side prerequisites once per project; the wizard handles the Claude Code side.

The Vertex AI setup wizard requires Claude Code v2.1.98 or later. Run claude --version to check.

[Enable the Vertex AI API](#1-enable-vertex-ai-api) for your project, then request access to the Claude models you want in the [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden). See [IAM configuration](#iam-configuration) for the permissions your account needs.



Run `claude`. At the login prompt, select **3rd-party platform**, then **Google Vertex AI**.



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](/en/settings), 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.

Region configuration

Claude Code supports Vertex AI 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 Vertex AI hostname for each form, including the aiplatform.eu.rep.googleapis.com and aiplatform.us.rep.googleapis.com hosts for multi-region locations.

Vertex AI 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 Vertex AI through environment variables instead of the wizard, for example in CI or a scripted enterprise rollout, follow the steps below.

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:

Navigate to the Vertex AI Model Garden
Search for "Claude" models
Request access to desired Claude models (for example, Claude Sonnet 4.6)
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.

When authenticating, Claude Code will automatically use the project ID from the ANTHROPIC_VERTEX_PROJECT_ID environment variable. To override this, set one of these environment variables: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, or GOOGLE_APPLICATION_CREDENTIALS.

4. Configure Claude Code

Set the following environment variables:

# Enable Vertex AI integration

# Optional: Override the Vertex endpoint URL for custom endpoints or gateways
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Optional: Disable prompt caching if needed

# Optional: Request 1-hour prompt cache TTL instead of the 5-minute default

# When CLOUD_ML_REGION=global, override region for models that don't support global endpoints

Most model versions have a corresponding VERTEX_REGION_CLAUDE_* variable. See the Environment variables reference for the full list. Check Vertex Model Garden to determine which models support global endpoints versus regional only.

Prompt caching is enabled automatically. To disable it, set DISABLE_PROMPT_CACHING=1. To request a 1-hour cache TTL instead of the 5-minute default, set ENABLE_PROMPT_CACHING_1H=1; cache writes with a 1-hour TTL are billed at a higher rate. 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.

MCP tool search is disabled by default on Vertex AI because the endpoint does not accept the required beta header. All MCP tool definitions load upfront instead. To opt in, set ENABLE_TOOL_SEARCH=true.

5. Pin model versions

Pin specific model versions when deploying to multiple users. Without pinning, model aliases such as sonnet and opus resolve to the latest version, which may not yet be enabled in your Vertex AI project when Anthropic releases an update. Claude Code falls back to the previous version at startup when the latest is unavailable, but pinning lets you control when your users move to a new model.

Set these environment variables to specific Vertex AI model IDs.

Without ANTHROPIC_DEFAULT_OPUS_MODEL, the opus alias on Vertex resolves to Opus 4.6. Set it to the Opus 4.7 ID to use the latest model:

For current and legacy model IDs, see Models overview. See Model configuration for the full list of environment variables.

Claude Code uses these default models when no pinning variables are set:

Model type	Default value
Primary model	`claude-sonnet-4-5@20250929`
Small/fast model	`claude-haiku-4-5@20251001`

To customize models further:

Startup model checks

When Claude Code starts with Vertex AI configured, it verifies that the models it intends to use are accessible in your project. This check requires Claude Code v2.1.98 or later.

If you have pi