> ## 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

> Integrate Portkey with Claude Code for enterprise-grade AI coding assistance with observability, reliability, and governance

### Universal provider (any model like gpt5.2, grok, kimi, etc)

You can use Claude Code with any model available through Portkey while keeping the same Anthropic-style `settings.json` structure.

Use the same setup as Anthropic, then swap:

* `x-portkey-provider` in `ANTHROPIC_CUSTOM_HEADERS` to your provider slug (for example, `@openai-prod`, `@xai-prod`, `@moonshot-prod`, etc.)
* `ANTHROPIC_MODEL` to your target model ID

```json theme={null}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.portkey.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_PORTKEY_API_KEY",
    "ANTHROPIC_CUSTOM_HEADERS": "x-portkey-api-key: YOUR_PORTKEY_API_KEY\nx-portkey-provider: @your-provider",
    "ANTHROPIC_MODEL": "$YOUR_MODEL"
  },
  "model": "$YOUR_MODEL"
}
```

<Note>
  `codex-5.3` models are currently not supported. Codex models require a Responses endpoint adapter, which is coming soon.
</Note>

[Claude Code](https://code.claude.com/docs/en/overview) is one of the most popular AI coding tools for boosting developer productivity. Platform teams use Portkey to roll out Claude Code across their organization—without handing out raw API keys or losing visibility into usage.

## Why Platform Teams Use Portkey

<CardGroup cols={2}>
  <Card title="Governance & Access Control" icon="shield-check">
    No raw API keys. Create a single config, add team members to workspaces, and enable Claude Code instantly. Track who's using what.
  </Card>

  <Card title="Cost Visibility" icon="chart-line">
    Claude Code can run up bills fast with agentic loops. See exactly what each team, project, or developer is spending—and set hard budget limits.
  </Card>

  <Card title="Workspace Separation" icon="building">
    Isolate teams with separate workspaces. Each gets its own budget, rate limits, and access controls. Perfect for enterprise multi-team setups.
  </Card>

  <Card title="Provider Agnostic" icon="shuffle">
    Route through Anthropic, Bedrock, or Vertex AI. Switch providers with a single config change—no developer workflow changes needed.
  </Card>
</CardGroup>

**For developers:** Setup takes 2 minutes. Copy a config, paste it, start coding.

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

  ```bash theme={null}
  claude update
  ```
</Note>

## Choose Your Provider

<CardGroup cols={3}>
  <Card title="Anthropic Direct" icon="bolt" href="/integrations/libraries/claude-code-anthropic">
    Route through Anthropic's API directly. Includes Max plan and OAuth support.
  </Card>

  <Card title="Amazon Bedrock" icon="aws" href="/integrations/libraries/claude-code-bedrock">
    Use Claude through AWS Bedrock with cross-region inference support.
  </Card>

  <Card title="Google Vertex AI" icon="google" href="/integrations/libraries/claude-code-vertex">
    Use Claude through Google Cloud's Vertex AI platform.
  </Card>
</CardGroup>

## How It Works

Portkey acts as an LLM gateway between Claude Code and your chosen provider. All requests route through Portkey's unified endpoint, giving you:

```
Claude Code → Portkey Gateway → Anthropic / Bedrock / Vertex AI
```

**Key difference from native Claude Code setup:** Portkey uses a single `ANTHROPIC_BASE_URL` endpoint for all providers. You don't need provider-specific URLs like `ANTHROPIC_BEDROCK_BASE_URL` or `ANTHROPIC_VERTEX_BASE_URL`.

## Quick start

### Option 1: Portkey CLI (recommended)

One command configures gateway routing, MCP servers, and team skills:

```bash theme={null}
npx portkey
```

<Card title="Portkey CLI reference" icon="terminal" href="/guides/coding-agents/agent-cli">
  Full CLI reference — flags, CI usage, and all options
</Card>

### Option 2: Manual setup

The configuration pattern is the same for all providers — only the provider slug and model names change:

<CodeGroup>
  ```json Anthropic theme={null}
  {
    "env": {
      "ANTHROPIC_BASE_URL": "https://api.portkey.ai",
      "ANTHROPIC_AUTH_TOKEN": "YOUR_PORTKEY_API_KEY",
      "ANTHROPIC_CUSTOM_HEADERS": "x-portkey-api-key: YOUR_PORTKEY_API_KEY\nx-portkey-provider: @anthropic-prod",
      "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-20250514",
      "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-20250514",
      "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-20250514"
    },
    "model": "claude-sonnet-4-20250514"
  }
  ```

  ```json Bedrock theme={null}
  {
    "env": {
      "ANTHROPIC_BASE_URL": "https://api.portkey.ai",
      "ANTHROPIC_AUTH_TOKEN": "YOUR_PORTKEY_API_KEY",
      "ANTHROPIC_CUSTOM_HEADERS": "x-portkey-api-key: YOUR_PORTKEY_API_KEY\nx-portkey-provider: @bedrock-prod",
      "ANTHROPIC_DEFAULT_SONNET_MODEL": "us.anthropic.claude-sonnet-4-20250514-v1:0",
      "ANTHROPIC_DEFAULT_OPUS_MODEL": "us.anthropic.claude-opus-4-20250514-v1:0",
      "ANTHROPIC_DEFAULT_HAIKU_MODEL": "us.anthropic.claude-haiku-4-20250514-v1:0"
    },
    "model": "us.anthropic.claude-sonnet-4-20250514-v1:0"
  }
  ```

  ```json Vertex AI theme={null}
  {
    "env": {
      "ANTHROPIC_BASE_URL": "https://api.portkey.ai",
      "ANTHROPIC_AUTH_TOKEN": "YOUR_PORTKEY_API_KEY",
      "ANTHROPIC_CUSTOM_HEADERS": "x-portkey-api-key: YOUR_PORTKEY_API_KEY\nx-portkey-provider: @vertex-prod",
      "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-20250514",
      "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-20250514",
      "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-20250514"
    },
    "model": "claude-sonnet-4-20250514"
  }
  ```
</CodeGroup>

<Warning>
  **Model names are required.** Each provider uses different model IDs. Without the correct model settings, requests will fail.
</Warning>

## Why Use Portkey with Claude Code?

### Cross-Provider Fallbacks

Never lose a coding session due to provider outages. Configure automatic failover:

```json theme={null}
{
  "strategy": { "mode": "fallback" },
  "targets": [
    { "provider": "@anthropic-prod" },
    { "provider": "@bedrock-prod" },
    { "provider": "@vertex-prod" }
  ]
}
```

### Budget Controls for Agentic Coding

Claude Code can run expensive agentic loops. Set hard limits:

* **Cost limits**: Maximum spend per day/week/month
* **Token limits**: Maximum tokens consumed
* **Rate limits**: Requests per minute/hour

### Full Session Observability

Track every request in your coding session:

* Request/response logs with full context
* Token usage and cost breakdowns
* Latency metrics
* Trace IDs for grouping related requests

### Caching

Reduce costs and latency for repeated queries (common in iterative coding):

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

## Common Configuration

### Forward Headers (Required)

Some Claude Code features need the `anthropic-beta` header forwarded. Add this to your [Portkey Config](/product/ai-gateway/configs):

```json theme={null}
{
  "provider": "@your-provider-slug",
  "forward_headers": ["anthropic-beta"]
}
```

### Trace IDs

Group requests by session or project:

```json theme={null}
{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "x-portkey-api-key: YOUR_KEY\nx-portkey-provider: @anthropic-prod\nx-portkey-trace-id: my-project-session"
  }
}
```

## Troubleshooting

| Symptom                       | Cause                   | Fix                                     |
| ----------------------------- | ----------------------- | --------------------------------------- |
| `API Error: 500 fetch failed` | Wrong base URL          | Use `https://api.portkey.ai` (no `/v1`) |
| Lightning symbol (⚡) in logs  | Passthrough request     | Check provider slug and API key         |
| Requests not appearing        | Old Claude Code version | Run `claude update`                     |

See provider-specific pages for detailed troubleshooting.

## Next Steps

<CardGroup cols={2}>
  <Card title="Portkey Configs" icon="gear" href="/product/ai-gateway/configs">
    Learn about fallbacks, load balancing, and routing strategies
  </Card>

  <Card title="Budget & Limits" icon="dollar-sign" href="/product/model-catalog/integrations#3-budget-%26-rate-limits">
    Set up spending controls for your team
  </Card>

  <Card title="Observability" icon="chart-line" href="/product/observability">
    Deep dive into logs, traces, and analytics
  </Card>

  <Card title="Model Catalog" icon="sparkles" href="/product/model-catalog">
    Manage providers and models across your organization
  </Card>
</CardGroup>