How to run Claude Code on Google Vertex AI
To run Claude Code on Google Vertex AI, enable the Agent Platform API in a Google Cloud project with billing turned on, then request access to the Claude models you want in Model Garden. After that, run claude, select 3rd-party platform at the login prompt, choose Google Vertex AI, and follow the wizard. It asks how you sign in to Google Cloud, which project and region to use, checks which Claude models your project can call, and saves it all to your user settings.
One naming note before you search the console for it. Google has renamed Vertex AI to Google Cloud's Agent Platform, and Anthropic's docs now use the new name. The Claude Code login menu still says Google Vertex AI, /status still reports the provider as Google Vertex AI, and the settings still use names like CLAUDE_CODE_USE_VERTEX. Same product, two names.
Once it is set up, every model request goes to Google Cloud in your project. You pay Google for the tokens, you track cost in GCP Billing, and access runs through IAM roles and Cloud Audit Logs. CLAUDE.md, skills, subagents, hooks, MCP servers, plugins and checkpoints all work the same as they do on a Claude plan.
Should you use Vertex AI or a Claude plan?
If you are building for yourself, start with a Claude plan and the Claude Code desktop app. It is the simplest setup and it includes features no cloud provider can reach. Which Claude plan for Claude Code covers that choice. Vertex AI is worth the setup when your company's money, data rules or servers already live in Google Cloud.
Claude plan vs Google Vertex AI for Claude Code, from Anthropic's deployment docs
| Claude plan (Pro, Max, Team, Enterprise) | Google Vertex AI (Agent Platform) | |
|---|---|---|
| Billing | Subscription, with pay as you go available on Team | Pay as you go through Google Cloud |
| Sign-in | claude.ai account | Google Cloud credentials |
| Cost tracking | Usage dashboard | GCP Billing |
| Audit and access | Team management, SSO, usage monitoring | IAM roles and Cloud Audit Logs |
| Where the models run | Anthropic's API | Google Cloud global, multi-region or regional endpoints |
| Desktop app | Yes | Only through managed settings or Claude Desktop on 3P |
- Your company already pays Google Cloud and wants Claude on the same bill.
- Your data rules say model traffic has to stay inside your own cloud project and region.
- You run Claude Code in CI or on servers that already have Google Cloud service accounts.
Step by step: set up Claude Code on Vertex AI with the wizard
- Enable the API. In your project, run gcloud services enable aiplatform.googleapis.com, or turn on the Agent Platform API in the console. The project needs billing enabled and quota in the region you plan to use.
- Request model access. Open Model Garden, search for Claude, and request the models you want. The docs say approval may take 24 to 48 hours, so do this a day before you need it.
- Start the wizard. Run claude, choose 3rd-party platform, then Google Vertex AI. If you are already signed in, run /login to open the same menu.
- Pick how you sign in. The wizard offers Application Default Credentials from gcloud, a service account key file, or credentials already in your environment. Then it asks for your project ID and region.
- Pin your models. The wizard checks which Claude models your project can call and lets you pin them. It writes the result to the env block of ~/.claude/settings.json.
- Check it. Run /status. The API provider line should say Google Vertex AI, with your GCP project, region and model listed below it.
Run /setup-vertex any time to change your credentials, project, region or pins. Because sign-in goes through Google Cloud, /logout is not available on this provider.
Pick the right region
This is where most Vertex setups go wrong. CLOUD_ML_REGION accepts three shapes, and not every Claude model is offered on every one.
Region options for Claude Code on Google Vertex AI
| Setting | Example | When to use it |
|---|---|---|
| Global endpoint | global | Better availability, and the docs suggest it when you hit 429 errors |
| Multi-region | eu or us | When data has to stay in one geography but you want more than one region |
| Single region | us-east5 | When your rules name a specific region |
If you use global and one of your models is not offered there, set that model's own region with its VERTEX_REGION_CLAUDE_* variable, for example VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5. If a region value is malformed, Claude Code ignores it: the per-model variables fall back to CLOUD_ML_REGION, and CLOUD_ML_REGION falls back to us-east5. Model Garden shows which models support the global endpoint under Supported features.
Pin your models before you roll it out
Same advice as on Bedrock, and I would not skip it. Without a pin, aliases like opus and sonnet resolve to Claude Code's built-in default for Vertex, which can lag the newest release or not be enabled in your project. The docs also warn that if you do not pin a primary model, it defaults to an Opus model and you pay the Opus rate, which is higher per token than Sonnet.
- Pin each family with ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL, using the model IDs your project has enabled.
- To make Sonnet the default instead of Opus, set ANTHROPIC_MODEL to the full Sonnet model ID.
- Background jobs like naming your session normally use a small, fast model. On Vertex, Claude Code uses Sonnet for them, because Haiku may not be enabled in every project. Set ANTHROPIC_DEFAULT_HAIKU_MODEL to a Haiku ID your project can call if you want Haiku there.
- If an unpinned default is not available, Claude Code falls back to an earlier or lower-tier model for that session and shows a notice. A pin makes your choice permanent.
Model choice is the biggest lever on cost, whichever provider you use. How much Claude Code costs per month breaks that down, and Claude Code environment variables covers where to set these so they stick.
The IAM role Claude Code needs
Give the account Claude Code runs as the roles/aiplatform.user role. The one permission that matters inside it is aiplatform.endpoints.predict, which covers calling the model and counting tokens. If your security team wants the narrowest possible access, a custom role with only that permission is enough.
- Use a separate project. Anthropic's docs suggest a dedicated GCP project for Claude Code to make cost tracking and access control simpler.
- Let expired logins refresh themselves. Add a gcpAuthRefresh setting such as "gcloud auth application-default login". Claude Code first checks whether your credentials have really expired and only runs the command if they have.
- Raise rate limits through Google. On Vertex, higher limits come from Google Cloud support, not Anthropic.
What you give up on Vertex AI
The core of Claude Code runs on Vertex, but some features need a claude.ai sign-in or a server feature Google does not offer. Here is what the feature availability docs list.
Claude Code features not available or limited on Google Vertex AI
| Feature | On Vertex AI | Use instead |
|---|---|---|
| Cloud scheduled tasks (/schedule) | Not available | /loop, which runs on your machine |
| Cloud sessions and Claude Code on mobile | Not available | GitHub Actions or GitLab CI/CD |
| Remote Control, Chrome extension, computer use, voice | Not available | No direct replacement |
| Fast mode, Advisor, Channels, server-managed settings, analytics dashboard | Not available | No direct replacement |
| Web search | Works on Opus 4, Sonnet 4, Haiku 4.5 and later models | Unlike Bedrock, where it is not available at all |
| Auto mode | Only on Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5 and Fable models | Pin a supported model |
| The standard desktop app | Partial | Managed settings, or Claude Desktop on 3P |
Web search is the one real difference from Bedrock. If your team does research inside Claude Code and you are choosing between the two clouds, that matters. Error reporting and telemetry to Anthropic are off by default here too.
Fixes for common Vertex AI errors
- "Could not load the default credentials": run gcloud auth application-default login, or set GOOGLE_APPLICATION_CREDENTIALS to a service account key file.
- "Model not found" 404: confirm the model is enabled in Model Garden and offered in the location you set. Some models are only on global or the eu and us multi-regions.
- 429 errors on a regional endpoint: check that both your main model and the background model are offered in that region, or switch CLOUD_ML_REGION to global.
- /status shows no provider line: the variables are not reaching Claude Code. Export them in the same shell you start claude from, or put them in the env block of your settings file.
Most of this is settings, so keep it in one file. The settings.json guide shows where the env block goes, and Claude Code GitHub Actions covers running it in CI against Vertex instead of cloud sessions.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I use Claude Code with Google Vertex AI?
Enable the Agent Platform API in your GCP project and request Claude model access in Model Garden. Then run claude, choose 3rd-party platform and Google Vertex AI, and follow the wizard. For scripts or CI, set CLAUDE_CODE_USE_VERTEX=1, CLOUD_ML_REGION and ANTHROPIC_VERTEX_PROJECT_ID instead.
Is Vertex AI the same as Google Cloud's Agent Platform?
Yes. Vertex AI is now called Google Cloud's Agent Platform. Claude Code's login menu, its /status output and its environment variables still use the Vertex name.
Do I need a Claude subscription to use Claude Code on Vertex AI?
No. You pay as you go through Google Cloud and sign in with Google Cloud credentials. Features that need a claude.ai sign-in, like cloud sessions, Remote Control and /schedule, are not available.
Does web search work in Claude Code on Vertex AI?
Yes, on Opus 4, Sonnet 4, Haiku 4.5 and later models. That is a difference from Amazon Bedrock, where web search is not available.
Which region should I use for Claude Code on Vertex AI?
Start with global for the best availability, then set a model's VERTEX_REGION_CLAUDE_* variable if that model is not offered on the global endpoint. Use eu, us or a single region only when your data rules require it.
Last reviewed by David Iya on October 25, 2026
