A Vertex AI coding agent uses models through your own Google Cloud project instead of a separate API key, so usage bills to that project and access follows its IAM roles. Claude Code runs Claude models on Vertex AI, OpenCode has Vertex AI built in, and Codex CLI has a built-in gcp provider. Every agent needs the same three things: the API enabled, a role that may call models, and Application Default Credentials (ADC) on your machine.
Since April 2026, Google’s docs call Vertex AI part of Gemini Enterprise Agent Platform, and Claude Code’s docs say Google Cloud’s Agent Platform. The aiplatform.googleapis.com endpoints and the steps below are the same.
Use Vertex AI with your agent
| Agent | Supported? | How | Note |
|---|---|---|---|
| Claude Code | Yes, Claude models | Run claude, choose 3rd-party platform → Google Vertex AI; or CLAUDE_CODE_USE_VERTEX=1 |
Claude Code runs Claude models only, not Gemini. Enable Claude in Model Garden first |
| Codex CLI | Not documented | model_provider = "gcp" in ~/.codex/config.toml |
OpenAI’s docs don’t say which Vertex models it serves |
| OpenCode | Yes, built in | GOOGLE_CLOUD_PROJECT plus ADC, optional VERTEX_LOCATION |
Model Garden lists what your project can use |
| Contenox | Yes, Gemini | Backends → Providers → Vertex AI (Google) | Lists Google’s own models, not Claude |
Before you start
-
A Google Cloud project with billing on and the API enabled. Google’s quickstart calls it the Agent Platform API; it’s the API behind
aiplatform.googleapis.com:gcloud config set project MY_PROJECT gcloud services enable aiplatform.googleapis.com -
A role that may call models. The predefined role is
roles/aiplatform.user, shown as Agent Platform User. -
Permission to bill the project. With your own Google login, requests name your project for billing and quota. That needs
serviceusage.services.use, which is in the Service Usage Consumer role. -
Credentials on your machine:
gcloud auth application-default loginOr impersonate a service account instead of downloading its key, which needs the Service Account Token Creator role on it:
gcloud auth application-default login --impersonate-service-account SA_NAME@MY_PROJECT.iam.gserviceaccount.com
Claude Code
First, open Model Garden in your project, search for Claude and request access to the models you want. Claude Code’s docs say approval may take a day or two.
Then run claude. At the login prompt, choose 3rd-party platform, then Google Vertex AI. The wizard asks how you sign in, your project and region, checks which Claude models you can call, and saves the result to ~/.claude/settings.json. Already signed in? Run /login for the same menu, or /setup-vertex to change the settings later.
To set it up by hand, in PowerShell on Windows:
$env:CLAUDE_CODE_USE_VERTEX = "1"
$env:CLOUD_ML_REGION = "global"
$env:ANTHROPIC_VERTEX_PROJECT_ID = "MY_PROJECT"
claude
On macOS or Linux:
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=MY_PROJECT
claude
Run /status. The API provider line should say Google Vertex AI, with your project and region below it.
The global endpoint trap: not every Claude model is offered on global. If you get a 404 “model not found”, check the model’s supported locations in Model Garden and either pick another model or set a region for it with its VERTEX_REGION_CLAUDE_* variable, listed in Claude Code’s environment variable reference.
For a team, pin the models with ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL, for example claude-opus-5-5. To refresh expired credentials automatically, add "gcpAuthRefresh": "gcloud auth application-default login" to ~/.claude/settings.json.
Gemini is not an option here. Claude Code runs Claude models only.
Codex CLI
Codex has a built-in Google Cloud provider. In ~/.codex/config.toml:
model_provider = "gcp"
[model_providers.gcp]
project_id = "MY_PROJECT"
location = "global"
Codex gets tokens by running gcloud auth application-default print-access-token, so the Google Cloud CLI must be installed and signed in. If you leave out project_id or location, Codex reads GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION; location defaults to global.
OpenAI’s docs only say to use a model your project can access on Vertex AI. They don’t list which ones, and Codex only speaks the Responses API, so check a model works before you rely on this.
OpenCode
OpenCode reads your project from the environment. In PowerShell on Windows:
$env:GOOGLE_CLOUD_PROJECT = "MY_PROJECT"
$env:VERTEX_LOCATION = "global"
opencode
On macOS or Linux:
export GOOGLE_CLOUD_PROJECT=MY_PROJECT
export VERTEX_LOCATION=global
opencode
It uses your gcloud auth application-default login credentials, or a service account key file in GOOGLE_APPLICATION_CREDENTIALS. VERTEX_LOCATION is optional and defaults to global. Pick a model with /models.
Contenox
- Run
gcloud auth application-default login, then start Contenox. - Open Backends → Providers and, under Cloud, choose Vertex AI (Google).
- In Vertex AI Base URL (project + location), enter the URL with your project ID, global:
https://aiplatform.googleapis.com/v1/projects/MY_PROJECT/locations/globalor regional:https://us-central1-aiplatform.googleapis.com/v1/projects/MY_PROJECT/locations/us-central1 - Select Connect and wait for Connected.
Contenox sends the project from the URL as the billing project, so you don’t set a separate quota project. To use a service account key, open Advanced and choose the file under Service Account Key JSON (optional); prefer ADC or impersonation, since key files are long-lived secrets.
Seen in practice, a key with no file: a service-account key can live in the operating system’s keyring and be loaded into an environment variable when a shell starts, so no
service-account.jsonstays on disk. Contenox then reads that variable when the backend is registered with--api-key-env; leaving the flag out makes it fall back to ADC, which fails if ADC is not signed in. The commands are in Can API keys stay out of files altogether?, from the write-up Stop your Keys in .env.
This connection lists Google’s own models, such as Gemini, not Claude. For Claude, use Anthropic or AWS Bedrock. Download Contenox.
Global or regional?
- Global (
aiplatform.googleapis.com, locationglobal): Google says it has higher availability and can reduce 429 “resource exhausted” errors. You don’t control which region processes a request. - Regional (
REGION-aiplatform.googleapis.com, locationREGION): requests stay in that region. Use it if you have data residency rules.
Models differ by location; Google’s locations page lists which models each one serves.
Which models work for a coding agent?
- Gemini (Contenox): use a current Gemini model; they support tool calls and long context. Flash models are faster and cheaper for routine edits; the larger ones are stronger on hard tasks.
- Claude (Claude Code): enable the models in Model Garden first, and check which locations serve them.
Common errors
| Error | Likely cause | Fix |
|---|---|---|
| 403, API not used or disabled | The API isn’t enabled in the project | Run gcloud services enable aiplatform.googleapis.com, wait a few minutes, try again |
| 403, permission denied on the model | Your account lacks the model role | Ask for roles/aiplatform.user on the project |
| 403, caller can’t use the project | You lack serviceusage.services.use on the project |
Ask for the Service Usage Consumer role, or check the project ID |
| “Could not load the default credentials” | No ADC on this machine | Run gcloud auth application-default login, then restart the agent |
invalid_grant on token refresh, or the model list stops loading |
The ADC login aged out or was revoked: an old login, a password change, an admin action, or a replaced credentials file. Listing models refreshes the token too | Run gcloud auth application-default login again |
| 404, model not found | The model isn’t enabled, or not offered in that location | Enable it in Model Garden, or switch location |
| 429, resource exhausted | Quota reached | Wait, switch to the global location, or request more quota |
What does it cost?
Vertex AI bills per token to your Cloud project, and quotas apply per project, region and model. See Google’s pricing page and quotas page.
Startup credits
If you are an eligible startup, the Google for Startups Cloud Program gives Google Cloud credits that cover model usage billed to the account, which can make this the cheapest way to run strong models for a while. Check which models count before you rely on it; partner models can be billed differently from the cloud’s own.
Related
- Gemini API key: the quick way to Gemini
- AWS Bedrock: the AWS counterpart
- How to choose a model for coding
- Keep secrets away from AI agents: why key files are risky