contenox

Vertex AI coding agent: Claude Code, Codex, OpenCode setup

Updated · Facts checked

MODEL PROVIDERSVertex AI (Google)

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 login

    Or 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

  1. Run gcloud auth application-default login, then start Contenox.
  2. Open Backends → Providers and, under Cloud, choose Vertex AI (Google).
  3. In Vertex AI Base URL (project + location), enter the URL with your project ID, global: https://aiplatform.googleapis.com/v1/projects/MY_PROJECT/locations/global or regional: https://us-central1-aiplatform.googleapis.com/v1/projects/MY_PROJECT/locations/us-central1
  4. 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.json stays 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, location global): 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, location REGION): 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

Esc to close