> ## Documentation Index
> Fetch the complete documentation index at: https://portkey-docs-add-third-party-integration-issues-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code with Google Vertex AI

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

Route [Claude Code](https://code.claude.com/docs/en/overview) through Google Vertex AI via Portkey. Get full observability, cost tracking, and budget controls with your existing GCP infrastructure.

See [Claude Code overview](/virtual_key_old/integrations/libraries/claude-code) for why platform teams use Portkey.

<Note>
  **Important:** Always use the latest version of Claude Code. Older versions may not work with Portkey's gateway.
</Note>

## Quick Start

<Steps>
  <Step title="Create a Virtual Key">
    Go to [Virtual Keys](https://app.portkey.ai/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.

    <Frame>
      <img src="https://mintcdn.com/portkey-docs-add-third-party-integration-issues-fixes/iw8u5vDH8VX-5kWU/images/integrations/openai/virtual-key-2.png?fit=max&auto=format&n=iw8u5vDH8VX-5kWU&q=85&s=a8c33fd72639726334d697df5a9b5701" width="500" data-path="images/integrations/openai/virtual-key-2.png" />
    </Frame>
  </Step>

  <Step title="Get Your Portkey API Key">
    Go to [API Keys](https://app.portkey.ai/api-keys) → Generate a new key.
  </Step>

  <Step title="Configure Claude Code">
    Edit `~/.claude/settings.json` (user-level) or `.claude/settings.json` (project-level):

    ```json theme={null}
    {
      "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

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

    <Note>
      Use `ANTHROPIC_VERTEX_BASE_URL` specifically for Vertex AI, not the generic base URL.
    </Note>
  </Step>
</Steps>

That's it! All Claude Code requests now route through Vertex AI via Portkey. Monitor usage in the [Portkey Dashboard](https://app.portkey.ai/logs).

## Using a Config

For advanced features like fallbacks, caching, or retries, create a [Portkey Config](/virtual_key_old/product/ai-gateway/configs):

<Steps>
  <Step title="Create a Config">
    Go to [Configs](https://app.portkey.ai/configs) → **Create Config**:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Update Claude Code Settings">
    Add the config to your settings:

    ```json theme={null}
    {
      "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
      }
    }
    ```
  </Step>
</Steps>

## Adding Metadata

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "virtual_key": "YOUR_VIRTUAL_KEY",
  "cache": { "mode": "simple" }
}
```

### Retries

Automatically retry failed requests:

```json theme={null}
{
  "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](https://app.portkey.ai/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:

```bash theme={null}
claude update
```

Or reinstall:

```bash theme={null}
curl -fsSL https://claude.ai/install.sh | bash
```

## Complete Example

Full configuration with all features enabled:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Access Controls" icon="lock" href="/virtual_key_old/product/enterprise-offering/access-control-management">
    Set up fine-grained permissions and audit logging
  </Card>

  <Card title="Budget Management" icon="coins" href="/virtual_key_old/product/ai-gateway/virtual-keys/budget-limits">
    Prevent overspending with hard budget limits
  </Card>
</CardGroup>