Google Vertex AI#

Route Google Vertex AI calls through Lockpin so they are priced and capped like any other provider’s. This page is for developers and admins who run Anthropic, Gemini or partner models on their own Google Cloud project.

How Vertex AI works with Lockpin#

Vertex AI calls carry an OAuth2 access token minted from a Google credential. Lockpin holds the credential, mints the token itself ahead of time, refreshes it in the background, and never forwards an agent’s own credential.

Lockpin serves Vertex AI under three names. All three use the same credential and share one token.

Base URL	Vertex API	Client	Model ids
`http://127.0.0.1:8787/vertex`	Anthropic models	The plain Anthropic SDK	`claude-sonnet-4-5@20250929`: the `@version` suffix as Vertex names it, or a versionless id where Vertex serves one
`http://127.0.0.1:8787/vertex-gemini`	Gemini `generateContent` and `streamGenerateContent`	google-genai, with this as its `base_url`	`gemini-3.8-flash`
`http://127.0.0.1:8787/vertex-openai/v1`	Vertex’s OpenAI-compatible endpoint (Chat Completions)	The OpenAI SDK	Partner models such as `meta/llama-4-maverick-17b-128e-instruct-maas`, `deepseek-ai/deepseek-v3.2-maas`, `openai/gpt-oss-120b-maas`, `qwen/qwen3-next-80b-a3b-instruct-maas`, and Gemini as `google/<id>`

Gemini is not served through /vertex. Under /vertex only /v1/messages is served, so nothing else is called with your token.

Before you begin#

Lockpin is installed. See Install.
You have a Google service-account key file for a project with access to the Vertex models you use, or the authorized_user file that gcloud auth application-default login writes.
You know the region you call Vertex in: a region such as us-east5 or europe-west1, the multi-regions us and eu, or global.

Set up Vertex AI on your machine#

Set the credential, project and region in the shell that starts Lockpin.

Windows

$env:GOOGLE_APPLICATION_CREDENTIALS = "C:\path\to\service-account.json"
$env:GOOGLE_CLOUD_PROJECT = "my-project"
$env:CLOUD_ML_REGION = "us-east5"
lockpin

macOS and Linux

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GOOGLE_CLOUD_PROJECT=my-project
export CLOUD_ML_REGION=us-east5
lockpin

Variable	What it holds
`GOOGLE_APPLICATION_CREDENTIALS`	A service-account key file, or the `authorized_user` file from `gcloud auth application-default login`. When it is unset, gcloud’s own application-default file is tried.
`GOOGLE_CLOUD_PROJECT`	The project. Without it, the key’s `project_id` is used.
`CLOUD_ML_REGION`	The region. `GOOGLE_CLOUD_REGION` and `GOOGLE_CLOUD_LOCATION` are read too.
`GOOGLE_OAUTH_ACCESS_TOKEN`	Instead of a key file: a ready token, such as `gcloud auth print-access-token` prints. It works for about an hour and is not refreshed.

Lockpin mints the access token when it starts. Until a token is minted, calls are refused with a message saying why.

Point your agent at Lockpin.

For Anthropic models, use the plain Anthropic client, not AnthropicVertex, which builds Vertex URLs and mints tokens itself:
```
import anthropic
client = anthropic.Anthropic(base_url="http://127.0.0.1:8787/vertex")
```
Put the Vertex model id, such as claude-sonnet-4-5@20250929, in model.
For Gemini, use google-genai with vertexai=True:
```
from google import genai
client = genai.Client(vertexai=True,
                      http_options={"base_url": "http://127.0.0.1:8787/vertex-gemini"})
```
For partner models, use the OpenAI SDK with base URL http://127.0.0.1:8787/vertex-openai/v1. The base Google documents, .../vertex-openai/v1/projects/<p>/locations/<l>/endpoints/openapi, works too.

On /vertex-gemini and /vertex-openai, Lockpin always calls under your project (a project in the path is ignored). It uses the location the path names, as Google’s SDKs build it, or else your region, so a model served in one region only can be reached.

Note

Workload Identity Federation, external_account and impersonated credentials, and the metadata server are not read.

Set up Vertex AI on a team node#

On a team node, the key is sealed in the node’s store under the name vertex, and agents hold only Lockpin tokens. An agent holding the key could mint tokens for anything the account may do, so the key stays off agent machines.

Seal the key on the node, as the node’s account:
```
lockpin keys seal vertex -project my-project -region us-east5 -sealed /var/lib/lockpin/lockpin-node.sealed < service-account.json
```
It reads the key file whole from stdin, takes the project from -project or the key’s project_id, and needs -region on the first seal. It prints nothing of the key: only the service account’s email, project, region, the store’s protection and the node key.
To rotate the key, reseal. A reseal keeps the project and region unless you give them:
```
lockpin keys seal vertex < new.json
```
A running node picks up a reseal within a second and starts minting from the new key at once. lockpin node install and -key-file take vertex_credentials_file=/path/sa.json, vertex_project=... and vertex_region=... among the provider=key lines.
Give agents the node’s address, such as http://<node>:8787/vertex, and their lpc_ token or lp_ key as the API key. With google-genai, the Lockpin key may also go in x-goog-api-key, where google-genai puts an API key.

A capability’s models caveat matches the id as sent, so mint it with claude-* for Anthropic models.

The access token#

Lockpin mints at start, again at two thirds of each token’s lifetime (40 minutes for Google’s hour), and after a failure with backoff from one second to a minute, serving the previous token meanwhile. The log shows the first mint and when the next is due.
The key signs a request that goes to oauth2.googleapis.com/token and nowhere else. Nothing else of the key leaves the machine.
No call waits on the token endpoint. A call over the cap is refused (402) as always. A call that fits but finds no valid token is refused with 503 vertex_token_unavailable and the reason, with its reservation released and no request made.
When Vertex refuses a token (401), the call comes back as vertex_token_rejected, nothing is billed, and the next refresh is brought forward.

How Vertex calls are priced#

Route	Price
`/vertex`	The id’s Anthropic base model (`claude-sonnet-4-5@20250929` as `claude-sonnet-4-5`), at Anthropic’s list price on `global`
`/vertex-gemini`	The Gemini table, plus models only Vertex lists, under `vertex-gemini/`
`/vertex-openai`	Google’s partner-model prices, under `vertex-openai/`

Every route is 10 percent more on a regional or multi-region endpoint than on global. On /vertex the premium follows your region; on the other two, the location the path names, else your region.

Anthropic models before Sonnet 4.5 keep their earlier Vertex prices, which the catalog does not know. Until you set them with -prices ("vertex/<id>": {...}), Lockpin applies the same 10 percent on a regional endpoint and so overstates them by that much. An explicit entry wins over the derived price.
Lockpin applies the 10 percent to every Gemini and partner model, so Gemini 2.5 and partner models on a regional location are overstated by that much until set with -prices.
A model whose base is not in the catalog is refused as unknown.

Check one line of your billing export against the ledger either way. See Prices and the price feed.

Limits#

On /vertex, of an agent’s request headers only Content-Type, Accept and User-Agent go to Vertex. Google’s own x-goog-* request headers could spend outside the cap and are dropped.
On a capped task these Gemini inputs are refused as unpriced: files in Cloud Storage (fileUri), cached content, audio input, inline parts that are neither text nor an image, and the tools whose cost the request does not show (googleSearch, googleMaps, enterprise web search, retrieval, urlContext, codeExecution). With no cap, or with -allow-unpriced, they go at the standard price.
Refused outright on Gemini: a body that names a key twice, candidateCount above 1, and the snake_case spellings generation_config, max_output_tokens and candidate_count. A Gemini stream is served with ?alt=sse only, which Google’s SDKs send.
Lockpin’s savings features do not edit Gemini calls, and Gemini models cannot be fallbacks or downgrades.
Not served in this version: Mistral’s models on Vertex, Vertex’s count-tokens endpoint (Lockpin uses its own estimate), provisioned throughput and batch prediction.

Verify#

Check the setup. lockpin doctor shows the credential line:
```
lockpin doctor -providers vertex
```
List the Vertex model ids Lockpin prices:
```
lockpin providers -models
```
Make one call through Lockpin and check that it appears in the meter at http://127.0.0.1:8787/lockpin/. Compare the ledger’s charge with your billing export.