Claude Code with Google Vertex AI

Route Claude Code through Google Vertex AI via Portkey. Get full observability, cost tracking, and budget controls with your existing GCP infrastructure. See Claude Code overview for why platform teams use Portkey.

Important: Always use the latest version of Claude Code. Older versions may not work with Portkey’s gateway.

Quick Start

Create a Virtual Key

Go to Virtual Keys → Create → Select Google Vertex AI.Enter your GCP credentials:

Service Account JSON key
GCP Project ID
Region (e.g., us-central1)

Save and copy the virtual key ID.

Get Your Portkey API Key

Go to API Keys → Generate a new key.

Configure Claude Code

Edit ~/.claude/settings.json (user-level) or .claude/settings.json (project-level):

{
  "env": {
    "ANTHROPIC_VERTEX_BASE_URL": "https://api.portkey.ai/v1",
    "ANTHROPIC_CUSTOM_HEADERS": "x-portkey-api-key: YOUR_PORTKEY_API_KEY\nx-portkey-provider: vertex-ai\nx-portkey-virtual-key: YOUR_VIRTUAL_KEY",
    "ANTHROPIC_MODEL": "claude-3-7-sonnet@20250219",
    "CLAUDE_CODE_SKIP_VERTEX_AUTH": 1,
    "CLAUDE_CODE_USE_VERTEX": 1
  }
}

Replace:

YOUR_PORTKEY_API_KEY with your Portkey API key
YOUR_VIRTUAL_KEY with your virtual key ID

Model names are required. Without these settings, Claude Code will use Anthropic Direct API model names which may fail on Vertex AI.

Use ANTHROPIC_VERTEX_BASE_URL specifically for Vertex AI, not the generic base URL.

That’s it! All Claude Code requests now route through Vertex AI via Portkey. Monitor usage in the Portkey Dashboard.

Using a Config

For advanced features like fallbacks, caching, or retries, create a Portkey Config:

Create a Config

Go to Configs → Create Config:

{
  "virtual_key": "YOUR_VIRTUAL_KEY",
  "override_params": {
    "model": "claude-3-7-sonnet@20250219"
  },
  "cache": { "mode": "simple" },
  "retry": { "attempts": 3, "on_status_codes": [429, 500, 502, 503] }
}

Save and copy the Config ID.

Update Claude Code Settings

Add the config to your settings:

{
  "env": {
    "ANTHROPIC_VERTEX_BASE_URL": "https://api.portkey.ai/v1",
    "ANTHROPIC_CUSTOM_HEADERS": "x-portkey-api-key: YOUR_PORTKEY_API_KEY\nx-portkey-config: YOUR_CONFIG_ID",
    "ANTHROPIC_MODEL": "claude-3-7-sonnet@20250219",
    "CLAUDE_CODE_SKIP_VERTEX_AUTH": 1,
    "CLAUDE_CODE_USE_VERTEX": 1
  }
}

Adding Metadata

Track Claude Code usage by team, project, or user:

{
  "env": {
    "ANTHROPIC_VERTEX_BASE_URL": "https://api.portkey.ai/v1",
    "ANTHROPIC_CUSTOM_HEADERS": "x-portkey-api-key: YOUR_PORTKEY_API_KEY\nx-portkey-provider: vertex-ai\nx-portkey-virtual-key: YOUR_VIRTUAL_KEY\nx-portkey-metadata: {\"_user\": \"john.doe\", \"team\": \"engineering\"}",
    "ANTHROPIC_MODEL": "claude-3-7-sonnet@20250219",
    "CLAUDE_CODE_SKIP_VERTEX_AUTH": 1,
    "CLAUDE_CODE_USE_VERTEX": 1
  }
}

Advanced Configuration

Fallbacks

Route to backup providers when Vertex AI fails. Create a config with fallback targets:

{
  "strategy": { "mode": "fallback" },
  "targets": [
    { "virtual_key": "vertex-virtual-key" },
    { "virtual_key": "anthropic-virtual-key" },
    { "virtual_key": "bedrock-virtual-key" }
  ]
}

Load Balancing

Distribute requests across multiple regions:

{
  "strategy": { "mode": "loadbalance" },
  "targets": [
    { "virtual_key": "vertex-us-central", "weight": 0.5 },
    { "virtual_key": "vertex-us-east", "weight": 0.5 }
  ]
}

Caching

Reduce costs and latency for repeated queries:

{
  "virtual_key": "YOUR_VIRTUAL_KEY",
  "cache": { "mode": "simple" }
}

Retries

Automatically retry failed requests:

{
  "virtual_key": "YOUR_VIRTUAL_KEY",
  "retry": { "attempts": 3, "on_status_codes": [429, 500, 502, 503] }
}

Budget Limits

Set spending controls on your virtual key:

Go to Virtual Keys → Select your Vertex AI virtual key
Click Edit → Budget & Limits
Configure:
- Cost limit: Maximum spend (e.g., $500/month)
- Rate limit: Requests per minute/hour

Budget limits prevent runaway costs from agentic coding sessions.

Troubleshooting

Claude Code Version Issues

Cause: Older versions of Claude Code may not be compatible. Fix: Update to the latest version:

claude update

Or reinstall:

curl -fsSL https://claude.ai/install.sh | bash

Complete Example

Full configuration with all features enabled:

{
  "env": {
    "ANTHROPIC_VERTEX_BASE_URL": "https://api.portkey.ai/v1",
    "ANTHROPIC_CUSTOM_HEADERS": "x-portkey-api-key: YOUR_PORTKEY_API_KEY\nx-portkey-config: YOUR_CONFIG_ID\nx-portkey-metadata: {\"_user\": \"john.doe\", \"project\": \"backend-api\"}",
    "ANTHROPIC_MODEL": "claude-3-7-sonnet@20250219",
    "CLAUDE_CODE_SKIP_VERTEX_AUTH": 1,
    "CLAUDE_CODE_USE_VERTEX": 1
  }
}

With Portkey Config:

{
  "strategy": { "mode": "fallback" },
  "targets": [
    { "virtual_key": "vertex-virtual-key" },
    { "virtual_key": "anthropic-virtual-key" }
  ],
  "cache": { "mode": "simple" },
  "retry": { "attempts": 3, "on_status_codes": [429, 500, 502, 503] }
}

Claude Code with Google Vertex AI

Quick Start

Using a Config

Adding Metadata

Advanced Configuration

Fallbacks

Load Balancing

Caching

Retries

Budget Limits

Troubleshooting

Claude Code Version Issues

Complete Example

Next Steps

Access Controls

Budget Management

​Quick Start

​Using a Config

​Adding Metadata

​Advanced Configuration

​Fallbacks

​Load Balancing

​Caching

​Retries

​Budget Limits

​Troubleshooting

​Claude Code Version Issues

​Complete Example

​Next Steps

Access Controls

Budget Management

Quick Start

Using a Config

Adding Metadata

Advanced Configuration

Fallbacks

Load Balancing

Caching

Retries

Budget Limits

Troubleshooting

Claude Code Version Issues

Complete Example

Next Steps