pi-vertex-anthropic

A pi provider extension for Anthropic Claude models hosted on Google Cloud Vertex AI, using Google Application Default Credentials (ADC) for authentication.

Use this extension if you want to use Claude in pi with billing through GCP, no API keys, and no gcloud subprocess calls — auth is handled by google-auth-library, the same way other Google Cloud client libraries do.

Features

Claude Opus, Sonnet, and Haiku on Google Cloud Vertex AI.
Application Default Credentials support: gcloud user credentials, service account JSON, GCE/GKE metadata server, Workload Identity, and other ADC sources.
No Anthropic API keys in pi.
No gcloud subprocess calls at request time.
Streaming, tool calls, prompt caching, image input, and thinking support through pi-ai's built-in Anthropic pipeline.
Interactive /login region picker, with environment-variable overrides for non-interactive setups.

When to use this

Use this extension if:

You want to use Anthropic Claude models from pi through Google Cloud Vertex AI.
You want billing, IAM, audit logs, org policy, and quota to stay in GCP.
You already use Application Default Credentials locally, on GCE/GKE, or with Workload Identity.
You do not want to manage Anthropic API keys in pi.

Do not use this extension if:

You want to call Anthropic's direct API with an Anthropic API key — use pi's built-in Anthropic provider instead.
Your GCP project does not have Vertex AI enabled or Anthropic Claude model access granted in Model Garden.
You need this extension to provision GCP resources or request Model Garden access for you; it only connects pi to an already-configured Vertex AI project.

Relationship to pi-ai's built-in `google-vertex` provider

pi 0.75+ ships a built-in google-vertex provider, so after /login you may see two Vertex-related providers in pi --list-models. They do not overlap — each serves a different model family:

Provider	Serves	SDK
`google-vertex` (built into pi-ai)	Gemini models on Vertex AI	`@google/genai`
`vertex-anthropic` (this extension)	Anthropic Claude models on Vertex AI	`@anthropic-ai/vertex-sdk`

Both authenticate through Application Default Credentials, but pi-ai's google-vertex provider does not expose Claude. Use this extension for Claude on Vertex; use the built-in provider for Gemini on Vertex.

Quick start

Install the package:

pi install npm:@pgilad/pi-vertex-anthropic

Set up Application Default Credentials once (any of these work):

gcloud auth application-default login
# or
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
# or run on GCE/GKE with an attached workload identity

Start pi, log in, and pick a model:

pi
/login          # choose "Google Vertex AI (ADC)" — prompts for region
/model          # choose vertex-anthropic/claude-opus-4-7

The login flow probes ADC, then prompts you to pick a Vertex AI region (global is the recommended default; us-east5, us-central1, europe-west1, europe-west4, asia-southeast1 are offered). If GOOGLE_CLOUD_LOCATION is set in your environment, the picker is skipped and that value is used.

Requirements

Node.js 22.19 or newer, as pi itself requires
pi 1.0 or newer. On pi 0.75.x–0.79.x, pin this extension to 0.7.x; on pi 0.73.x (@mariozechner/*), pin it to 0.1.x.
A GCP project with Vertex AI enabled and Anthropic Claude models granted via Model Garden
ADC configured via gcloud user credentials, service account JSON, the GCE/GKE metadata server, Workload Identity, or any other ADC source
The ADC principal must have permission to call Vertex AI prediction APIs, typically via roles/aiplatform.user on the project

No gcloud CLI is required at request time. The extension only uses gcloud if that's how you configured ADC; pure service account or Workload Identity setups work without it.

GCP/IAM setup

At minimum, the GCP project you use with this extension needs:

The Vertex AI API enabled.
Anthropic Claude model access granted in Vertex AI Model Garden.
An ADC identity authorized to call Vertex AI prediction APIs.

For most users, granting the ADC principal the Vertex AI User role is sufficient:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:you@example.com" \
  --role="roles/aiplatform.user"

For service-account ADC, grant the role to the service account instead:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:my-service-account@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

If your organization uses custom roles or stricter IAM, make sure the principal can invoke Vertex AI publisher/model prediction endpoints for the Anthropic models you enabled.

Compatibility

Extension version	pi namespace
`0.1.x`	`@mariozechner/*` (pi 0.73.x) — frozen
`0.2.x`–`0.7.x`	`@earendil-works/*` (pi 0.75.x–0.79.x) — frozen
`0.8.x` and newer	`@earendil-works/*` (pi 1.0+)

See CHANGELOG.md for the rename details.

Install

The GitHub repository is pgilad/pi-vertex-anthropic; the published npm package is scoped as @pgilad/pi-vertex-anthropic.

Global install

pi install npm:@pgilad/pi-vertex-anthropic

Project-local install

Use -l to record the package in the current project's .pi/settings.json instead of your global pi settings, so it ships with the project:

pi install -l npm:@pgilad/pi-vertex-anthropic

Try from a local checkout

For development against this repository:

git clone https://github.com/pgilad/pi-vertex-anthropic ~/repos/pi-vertex-anthropic
cd ~/repos/pi-vertex-anthropic && npm install
pi install ~/repos/pi-vertex-anthropic

Configuration

The extension reads (in order):

Setting	Sources
Project ID	`ANTHROPIC_VERTEX_PROJECT_ID` → `GOOGLE_CLOUD_PROJECT` → `GCLOUD_PROJECT` → `quota_project_id` field of `~/.config/gcloud/application_default_credentials.json` → `google-auth-library`'s `auth.getProjectId()`
Region	`GOOGLE_CLOUD_LOCATION` → `CLOUD_ML_REGION` → interactive picker at `/login` → `"global"`
Credentials	Sources resolved by `new GoogleAuth().getClient()` — `GOOGLE_APPLICATION_CREDENTIALS`, ADC file, GCE/GKE metadata server, Workload Identity

At request time, the environment variables come first, then the project and region that /login stored, then the ADC file. So you can change the project or region with an environment variable, without a new /login.

In most cases, gcloud auth application-default login is the only setup needed — the project ID is recorded in the ADC file's quota_project_id and google-auth-library finds the credentials automatically.

For explicit shell-based setup, use the extension-specific project variable plus a Vertex AI region:

export ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project
export GOOGLE_CLOUD_LOCATION=global

For service-account ADC:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project
export GOOGLE_CLOUD_LOCATION=global

If you want to avoid setting GOOGLE_CLOUD_PROJECT globally (because it affects gcloud, Terraform, bq, and other tools), don't set it — the extension falls back to the ADC file or ANTHROPIC_VERTEX_PROJECT_ID.

Verify your setup

After /login, list the registered models:

pi --list-models | grep vertex-anthropic

Expected output:

vertex-anthropic  claude-fable-5                         1M       128K     yes       yes
vertex-anthropic  claude-fable-5-1                       1M       128K     yes       yes
vertex-anthropic  claude-haiku-4-5@20251001              200K     64K      yes       yes
vertex-anthropic  claude-opus-4-6                        1M       128K     yes       yes
vertex-anthropic  claude-opus-4-7                        1M       128K     yes       yes
vertex-anthropic  claude-opus-4-8                        1M       128K     yes       yes
vertex-anthropic  claude-opus-5                          1M       128K     yes       yes
vertex-anthropic  claude-opus-5-5                        1M       128K     yes       yes
vertex-anthropic  claude-sonnet-4-6                      1M       128K     yes       yes
vertex-anthropic  claude-sonnet-5                        1M       128K     yes       yes
vertex-anthropic  claude-sonnet-5-5                      1M       128K     yes       yes

Smoke test:

pi --provider vertex-anthropic --model claude-opus-4-7 --no-tools --thinking off \
   -p "Reply with exactly: smoke test passed"

Troubleshooting

`ADC not configured`

pi could not find usable Application Default Credentials. Configure an ADC source, then run /login again:

gcloud auth application-default login
# or
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

`no GCP project resolvable`

Credentials were found, but no project ID could be determined. Set an explicit project for this extension:

export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id

Or record a quota project in your local ADC file:

gcloud auth application-default set-quota-project your-gcp-project-id

Permission denied

Check that:

Vertex AI API is enabled in the project.
The Anthropic Claude model is enabled for the project in Model Garden.
The ADC principal has permission to call Vertex AI prediction APIs, typically roles/aiplatform.user.
You are using the intended project ID; ANTHROPIC_VERTEX_PROJECT_ID overrides ADC project detection.

Model or region not found

Claude availability on Vertex AI varies by region and model, and Google/Anthropic can change regional availability independently for each model. A model that works in one region may fail in another, and newly released models may not appear everywhere at the same time.

Try the global region first:

export GOOGLE_CLOUD_LOCATION=global

If you need a specific region, confirm that the selected Claude model is available there in the current Anthropic/Vertex AI documentation. If one model fails in your region, test another registered model before assuming ADC or pi is misconfigured.

`/login` succeeds but requests still fail

/login only verifies that ADC exists and stores the selected project and region in pi. Access tokens are still acquired by google-auth-library at request time, so request failures usually mean project, IAM, Model Garden access, quota, or region/model availability issues.

You don't need to restart pi after you change ADC (for example, re-run gcloud auth application-default login because the old refresh token expired). When a token request fails, the extension reads ADC again and tries once more. /login also rebuilds the Vertex client, which picks up a different ADC account even while the old credential still works.

Choosing a model

Pick interactively with /model, or pass on the command line:

pi --provider vertex-anthropic --model claude-opus-4-6
pi --provider vertex-anthropic --model claude-opus-4-7
pi --provider vertex-anthropic --model claude-opus-4-8
pi --provider vertex-anthropic --model claude-opus-5
pi --provider vertex-anthropic --model claude-opus-5-5
pi --provider vertex-anthropic --model claude-sonnet-4-6
pi --provider vertex-anthropic --model claude-sonnet-5
pi --provider vertex-anthropic --model claude-sonnet-5-5
pi --provider vertex-anthropic --model claude-haiku-4-5@20251001
pi --provider vertex-anthropic --model claude-fable-5
pi --provider vertex-anthropic --model claude-fable-5-1

Model IDs are taken verbatim from Anthropic's Vertex AI docs and the Vertex Model Garden catalog:

Model	Vertex AI ID	Context	Max output	Thinking	`xhigh`	`max`
Claude Opus 4.6	`claude-opus-4-6`	1M	128K	adaptive (effort)	clamped to `high`	✅
Claude Opus 4.7	`claude-opus-4-7`	1M	128K	adaptive (effort)	✅	✅
Claude Opus 4.8	`claude-opus-4-8`	1M	128K	adaptive (effort)	✅	✅
Claude Opus 5	`claude-opus-5`	1M	128K	adaptive (effort)	✅	✅
Claude Opus 5.5	`claude-opus-5-5`	1M	128K	adaptive (effort)	✅	✅
Claude Sonnet 4.6	`claude-sonnet-4-6`	1M	128K	adaptive (effort)	clamped to `high`	✅
Claude Sonnet 5	`claude-sonnet-5`	1M	128K	adaptive (effort)	✅	✅
Claude Sonnet 5.5	`claude-sonnet-5-5`	1M	128K	adaptive (effort)	✅	✅
Claude Haiku 4.5	`claude-haiku-4-5@20251001`	200K	64K	extended (budget)	—	—
Claude Fable 5	`claude-fable-5`	1M	128K	adaptive (effort)	✅	✅
Claude Fable 5.1	`claude-fable-5-1`	1M	128K	adaptive (effort)	✅	✅

Vertex versioning. claude-opus-4-8 and claude-fable-5 are listed in the Vertex Model Garden catalog with versionId: default (no dated @YYYYMMDD alias yet).

Cost, limits, thinking levels, compatibility flags, and prompt cache lifetimes follow pi's built-in Anthropic model list. test/registry.test.ts compares them and lists the deliberate differences for Vertex:

No model uses strict tool schemas. Vertex treats them as the structured_outputs partner-model feature, which an organization policy (constraints/vertexai.allowedPartnerModelFeatures) can disallow. Every request with pi's tools then fails with HTTP 400.
Sonnet 5 does not get a temperature: Vertex rejects it for that model.
Haiku 4.5 has no prompt cache lifetimes, so pi does not keep its cache warm: its cache-warming replays would change the thinking budget.

pi maps thinking levels automatically:

Opus 4.7, Opus 4.8, Opus 5, Opus 5.5, Sonnet 5, Sonnet 5.5, Fable 5, Fable 5.1 (adaptive, with xhigh): --thinking low|medium|high|xhigh|max becomes the SDK's effort parameter directly.
Opus 4.6 and Sonnet 4.6 (adaptive, no xhigh slot): low|medium|high|max pass through; xhigh is clamped to high so Anthropic's API doesn't 400 the request. Matches upstream pi-ai's mapThinkingLevelToEffort fallback when a model's thinkingLevelMap lacks an xhigh entry.
Haiku 4.5 (extended/budgeted thinking): pi thinking levels map to thinkingBudgetTokens using the same default budgets as pi's built-in Anthropic provider (xhigh uses the high budget) or your settings.thinkingBudgets overrides. See pi's thinkingBudgets settings docs for the exact shape. The extension grows max_tokens (capped at the model maximum) to absorb the budget, as pi does, so --max-tokens 4000 --thinking high won't violate Anthropic's budget_tokens < max_tokens constraint.

The extension builds each request the way pi's built-in Anthropic provider does. test/parity.test.ts sends the same requests through both and fails when they differ.

Security notes

The extension does not store Google access tokens, refresh tokens, service-account keys, or Anthropic API keys.
pi stores only a sentinel auth record for this provider, plus the resolved projectId and selected region, in its normal auth storage.
Request-time Google access tokens are acquired and refreshed by google-auth-library through @anthropic-ai/vertex-sdk.
Model requests are sent to Google Cloud Vertex AI for the configured project and region.
No gcloud auth print-access-token subprocess is run per request.
If you use GOOGLE_APPLICATION_CREDENTIALS, the referenced service-account JSON file remains in its configured location; this extension only relies on Google ADC resolution to find it.

How it works

index.ts registers the provider. The code is in src/: resolution.ts (project and region), login.ts (/login and refresh), client.ts (the Vertex client), thinking.ts and stream.ts (request options and streaming), and models.ts (the model list).

Auth. oauth.login calls new GoogleAuth().getClient() from google-auth-library. If credentials are available, pi stores a sentinel credential with the project and region in its auth storage and revalidates it daily via oauth.refreshToken. pi hands the project and region back with each request: oauth.getApiKey turns the stored credential into the apiKey that pi passes to streamSimple. The extension does not read pi's auth.json. Real per-request access token refresh is handled by google-auth-library inside the SDK; if a token request fails, the extension reads ADC again and tries once more, so changed ADC needs no restart.
Streaming. streamSimple constructs an AnthropicVertex client (cached by project and region) and injects it into pi-ai's built-in Anthropic Messages implementation (anthropicMessagesApi().stream from @earendil-works/pi-ai/compat) via its client option. The Vertex SDK and google-auth-library load on the first request, so they do not slow down pi's startup. All message conversion, SSE parsing, tool-call handling, prompt caching, and thinking-block plumbing come from upstream pi-ai unchanged. pi-ai's own streamSimple does not accept a client, so the extension maps the request options itself, the same way; test/parity.test.ts compares the two.

No subprocess calls, no hand-rolled SSE parser, no Anthropic Messages reimplementation.

Similar projects

skyfallsin/pi-vertex-anthropic — an earlier extension that solves the same problem. It uses gcloud auth print-access-token (subprocess per request) instead of google-auth-library, and implements its own Anthropic streaming pipeline rather than delegating to pi-ai's built-in Anthropic support.
SafeAI-Lab-X/ClawKeeper — internal AnthropicVertex integration inside a broader watcher tool. The architectural pattern this extension follows (AnthropicVertex client injected into pi-ai's streamAnthropic) is adapted from clawkeeper-watcher/src/agents/anthropic-vertex-stream.ts.
gsd-build/gsd-2 — fork of pi-mono with a native anthropic-vertex provider added at the SDK layer. This is likely the cleanest long-term direction if upstream merges similar support.

Development

npm install
npm run check    # tsc --noEmit
npm run lint     # biome
npm test         # vitest

CI also runs the type check and the tests with the oldest pi that peerDependencies accepts, on the oldest Node that engines accepts.

Local iteration without reinstalling:

pi -e /path/to/pi-vertex-anthropic/index.ts

License

MIT

Name		Name	Last commit message	Last commit date
.github		.github
src		src
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
index.ts		index.ts
mise.toml		mise.toml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

pi-vertex-anthropic

Features

When to use this

Relationship to pi-ai's built-in `google-vertex` provider

Quick start

Requirements

GCP/IAM setup

Compatibility

Install

Global install

Project-local install

Try from a local checkout

Configuration

Verify your setup

Troubleshooting

`ADC not configured`

`no GCP project resolvable`

Permission denied

Model or region not found

`/login` succeeds but requests still fail

Choosing a model

Security notes

How it works

Similar projects

Development

License

About

Releases

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

pi-vertex-anthropic

Features

When to use this

Relationship to pi-ai's built-in google-vertex provider

Quick start

Requirements

GCP/IAM setup

Compatibility

Install

Global install

Project-local install

Try from a local checkout

Configuration

Verify your setup

Troubleshooting

ADC not configured

no GCP project resolvable

Permission denied

Model or region not found

/login succeeds but requests still fail

Choosing a model

Security notes

How it works

Similar projects

Development

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages

Relationship to pi-ai's built-in `google-vertex` provider

`ADC not configured`

`no GCP project resolvable`

`/login` succeeds but requests still fail