> ## 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.¶
¶
export const ContactSalesCard = ({surface}) => {¶
const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;¶
const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">¶
<line x1="5" y1="12" x2="19" y2="12" />¶
<polyline points="12 5 19 12 12 19" />¶
</svg>;¶
const STYLES = `¶
.cc-cs {¶
--cs-slate: #141413;¶
--cs-clay: #d97757;¶
--cs-clay-deep: #c6613f;¶
--cs-gray-000: #ffffff;¶
--cs-gray-700: #3d3d3a;¶
--cs-border-default: rgba(31, 30, 29, 0.15);¶
font-family: inherit;¶
}¶
.dark .cc-cs {¶
--cs-slate: #f0eee6;¶
--cs-gray-000: #262624;¶
--cs-gray-700: #bfbdb4;¶
--cs-border-default: rgba(240, 238, 230, 0.14);¶
}¶
.cc-cs-card {¶
display: flex; align-items: center; justify-content: space-between;¶
gap: 16px; padding: 14px 16px; margin: 0;¶
background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);¶
border-radius: 8px; flex-wrap: wrap;¶
}¶
.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }¶
.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }¶
.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }¶
.cc-cs-btn-clay {¶
display: inline-flex; align-items: center; gap: 8px;¶
background: var(--cs-clay-deep); color: #fff; border: none;¶
border-radius: 8px; padding: 8px 14px;¶
font-size: 13px; font-weight: 500;¶
transition: background-color 0.15s; white-space: nowrap;¶
}¶
.cc-cs-btn-clay:hover { background: var(--cs-clay); }¶
.cc-cs-btn-ghost {¶
display: inline-flex; align-items: center; gap: 8px;¶
background: transparent; color: var(--cs-gray-700);¶
border: 0.5px solid var(--cs-border-default);¶
border-radius: 8px; padding: 8px 14px;¶
font-size: 13px; font-weight: 500;¶
}¶
.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }¶
.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }¶
@media (max-width: 720px) {¶
.cc-cs-actions { width: 100%; }¶
}¶
`;¶
return <div className="cc-cs not-prose">¶
<style>{STYLES}</style>¶
<div className="cc-cs-card">¶
<div className="cc-cs-text">¶
<strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.¶
</div>¶
<div className="cc-cs-actions">¶
<a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">¶
View plans¶
</a>¶
<a href={`https://www.anthropic.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">¶
Contact sales {iconArrowRight()}¶
</a>¶
</div>¶
</div>¶
</div>;¶
};¶
¶
export const Experiment = ({flag, treatment, children}) => {¶
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;¶
};¶
¶
<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="vertex" />} />¶
¶
## 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](#sign-in-with-vertex-ai) below. To deploy Claude Code across a team, use the [manual setup](#set-up-manually) steps and [pin your model versions](#5-pin-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.¶
¶
<Note>¶
The Vertex AI setup wizard requires Claude Code v2.1.98 or later. Run `claude --version` to check.¶
</Note>¶
¶
<Steps>¶
<Step title="Enable Claude models in your GCP project">¶
[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.¶
</Step>¶
¶
<Step title="Start Claude Code and choose Vertex AI">¶
Run `claude`. At the login prompt, select **3rd-party platform**, then **Google Vertex AI**.¶
</Step>¶
¶
<Step title="Follow the wizard prompts">¶
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.¶
</Step>¶
</Steps>¶
¶
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 can be used with both Vertex AI [global](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai) and regional endpoints.¶
¶
<Note>¶
Vertex AI may not support the Claude Code default models in all [regions](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models) or on [global endpoints](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models). You may need to switch to a supported region, use a regional endpoint, or specify a supported model.¶
</Note>¶
¶
## 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:¶
¶
```bash theme={null}¶
# 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](https://console.cloud.google.com/vertex-ai/model-garden)¶
2. Search for "Claude" models¶
3. Request access to desired Claude models (for example, Claude Sonnet 4.6)¶
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](https://cloud.google.com/docs/authentication).¶
¶
<Note>¶
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`.¶
</Note>¶
¶
### 4. Configure Claude Code¶
¶
Set the following environment variables:¶
¶
```bash theme={null}¶
# Enable Vertex AI integration¶
export CLAUDE_CODE_USE_VERTEX=1¶
export CLOUD_ML_REGION=global¶
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID¶
¶
# 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¶
export DISABLE_PROMPT_CACHING=1¶
¶
# When CLOUD_ML_REGION=global, override region for models that don't support global endpoints¶
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5¶
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1¶
```¶
¶
Most model versions have a corresponding `VERTEX_REGION_CLAUDE_*` variable. See the [Environment variables reference](/en/env-vars) for the full list. Check [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) to determine which models support global endpoints versus regional only.¶
¶
[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/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. Pin model versions¶
¶
<Warning>¶
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](#startup-model-checks) to the previous version at startup when the latest is unavailable, but pinning lets you control when your users move to a new model.¶
</Warning>¶
¶
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:¶
¶
```bash theme={null}¶
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'¶
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'¶
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'¶
```¶
¶
For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) 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:¶
¶
```bash theme={null}¶
export ANTHROPIC_MODEL='claude-opus-4-7'¶
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'¶
```¶
¶
## 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 pinned a model version that is older than the current Claude Code default, and your project can invoke the newer version, Claude Code prompts you to update the pin. Accepting writes the new model ID to your [user settings file](/en/settings) and restarts Claude Code. Declining is remembered until the next default version change.¶
¶
If you have not pinned a model and the current default is unavailable in your project, Claude Code falls back to the previous version for the current session and shows a notice. The fallback is not persisted. Enable the newer model in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) or [pin a version](#5-pin-model-versions) to make the choice permanent.¶
¶
## IAM configuration¶
¶
Assign the required IAM permissions:¶
¶
The `roles/aiplatform.user` role includes the required permissions:¶
¶
* `aiplatform.endpoints.predict` - Required for model invocation and token counting¶
¶
For more restrictive permissions, create a custom role with only the permissions above.¶
¶
For details, see [Vertex IAM documentation](https://cloud.google.com/vertex-ai/docs/general/access-control).¶
¶
<Note>¶
Create a dedicated GCP project for Claude Code to simplify cost tracking and access control.¶
</Note>¶
¶
## 1M token context window¶
¶
Claude Opus 4.7, Opus 4.6, and Sonnet 4.6 support the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) on Vertex AI. Claude Code automatically enables the extended context window when you select a 1M model variant.¶
¶
To enable the 1M context window for yourhe [setup wizard](#sign-in-with-vertex-ai) offers a 1M context option when it pins models. To enable it for a manually pinned model instead, append `[1m]` to the model ID. See [Pin models for third-party deployments](/en/model-config#pin-models-for-third-party-deployments) for details.¶
¶
## Troubleshooting¶
¶
If you encounter quota issues:¶
¶
* Check current quotas or request quota increase through [Cloud Console](https://cloud.google.com/docs/quotas/view-manage)¶
¶
If you encounter "model not found" 404 errors:¶
¶
* Confirm model is Enabled in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)¶
* Verify you have access to the specified region¶
* If using `CLOUD_ML_REGION=global`, check that your models support global endpoints in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) under "Supported features". For models that don't support global endpoints, either:¶
* Specify a supported model via `ANTHROPIC_MODEL` or `ANTHROPIC_DEFAULT_HAIKU_MODEL`, or¶
* Set a regional endpoint using `VERTEX_REGION_<MODEL_NAME>` environment variables¶
¶
If you encounter 429 errors:¶
¶
* For regional endpoints, ensure the primary model and small/fast model are supported in your selected region¶
* Consider switching to `CLOUD_ML_REGION=global` for better availability¶
¶
## Additional resources¶
¶
* [Vertex AI documentation](https://cloud.google.com/vertex-ai/docs)¶
* [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing)¶
* [Vertex AI quotas and limits](https://cloud.google.com/vertex-ai/docs/quotas)¶