Claude Code with Google Vertex AI

Route Claude Code through Google Vertex AI via Portkey for observability, governance, and reliability

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

1. 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.

   
2. Get Your Portkey API Key

   Go to API Keys → Generate a new key.

3. 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:

1. 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.

2. 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:

1. Go to Virtual Keys → Select your Vertex AI virtual key
2. Click Edit → Budget & Limits
3. 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] }
}

Next Steps

Access Controls

Set up fine-grained permissions and audit logging

Budget Management

Prevent overspending with hard budget limits