diff --git a/docs/my-website/docs/tutorials/claude_code_max_subscription.md b/docs/my-website/docs/tutorials/claude_code_max_subscription.md new file mode 100644 index 0000000000..399051d41e --- /dev/null +++ b/docs/my-website/docs/tutorials/claude_code_max_subscription.md @@ -0,0 +1,357 @@ +import Image from '@theme/IdealImage'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Using Claude Code Max Subscription + +
+ + +Route Claude Code Max subscription traffic through LiteLLM AI Gateway. +
+ +**Why Claude Code Max over direct API?** +- **Lower costs** — Claude Code Max subscriptions are cheaper for Claude Code power users than per-token API pricing + +**Why route through LiteLLM?** +- **Cost attribution** — Track spend per user, team, or key +- **Budgets & rate limits** — Set spending caps and request limits +- **Guardrails** — Apply content filtering and safety controls to all requests + + + +## Quick Start Video + +Watch the end-to-end walkthrough of setting up Claude Code with LiteLLM Gateway: + + + +## Prerequisites + +- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) installed +- Claude Max subscription +- LiteLLM Gateway running + +## Step 1: Configure LiteLLM Proxy + +Create a `config.yaml` with the critical `forward_client_headers_to_llm_api: true` setting: + +```yaml showLineNumbers title="config.yaml" +model_list: + - model_name: anthropic-claude + litellm_params: + model: anthropic/claude-sonnet-4-20250514 + + - model_name: claude-3-5-sonnet-20241022 + litellm_params: + model: anthropic/claude-3-5-sonnet-20241022 + + - model_name: claude-3-5-haiku-20241022 + litellm_params: + model: anthropic/claude-3-5-haiku-20241022 + +general_settings: + forward_client_headers_to_llm_api: true # Required: forwards OAuth token to Anthropic + +litellm_settings: + master_key: os.environ/LITELLM_MASTER_KEY +``` + +:::info Why `forward_client_headers_to_llm_api`? + +This setting forwards the user's OAuth token (in the `Authorization` header) through LiteLLM to the Anthropic API, enabling per-user authentication with their Max subscription while LiteLLM handles tracking and controls. + +::: + +## Step 2: Start LiteLLM Proxy + +```bash showLineNumbers title="Start LiteLLM Proxy" +litellm --config /path/to/config.yaml + +# RUNNING on http://0.0.0.0:4000 +``` + +## Walkthrough + +### Part 1: Create a Virtual Key in LiteLLM + +Navigate to the LiteLLM Dashboard and create a new virtual key for Claude Code usage. + +#### 1.1 Open Virtual Keys Page + +Navigate to the Virtual Keys section in the LiteLLM Dashboard. + + + +#### 1.2 Click "Create New Key" + + + +#### 1.3 Configure Key Details + +Enter a key name (e.g., `claude-code-test`) and select the models you want to allow access to. + + + +#### 1.4 Select Models + +Choose the Anthropic models that should be accessible via this key (e.g., `anthropic-claude`, `claude-4.5-haiku`). + + + +#### 1.5 Confirm Model Selection + + + +#### 1.6 Create the Key + +Click "Create Key" to generate your virtual key. Copy the generated key value (e.g., `sk-otsclFlEblQ-6D60ua2IZg`). + + + +--- + +### Part 2: Sign into Claude Code Max Plan (Client Side) + +Set up Claude Code environment variables and authenticate with your Max subscription. + +#### 2.1 Set Environment Variables + +Configure Claude Code to use LiteLLM Gateway with your virtual key: + +```bash showLineNumbers title="Configure Claude Code Environment Variables" +export ANTHROPIC_BASE_URL=http://localhost:4000 +export ANTHROPIC_MODEL="anthropic-claude" +export ANTHROPIC_CUSTOM_HEADERS="x-litellm-api-key: Bearer sk-otsclFlEblQ-6D60ua2IZg" +``` + + + +#### Environment Variables Explained + +| Variable | Description | +|----------|-------------| +| `ANTHROPIC_BASE_URL` | Points Claude Code to your LiteLLM Gateway endpoint | +| `ANTHROPIC_MODEL` | The model name configured in your LiteLLM `config.yaml` | +| `ANTHROPIC_CUSTOM_HEADERS` | The `x-litellm-api-key` header for LiteLLM authentication | + +#### 2.2 Launch Claude Code + +Start Claude Code: + +```bash showLineNumbers title="Launch Claude Code" +claude +``` + + + +#### 2.3 Select Login Method + +Choose "Claude account with subscription" (Pro, Max, Team, or Enterprise). + + + +#### 2.4 Authorize in Browser + +Claude Code opens your browser to authenticate. Click "Authorize" to connect your Claude Max account. + + + +#### 2.5 Login Successful + +After authorization, you'll see the login success confirmation. + + + +#### 2.6 Complete Setup + +Press Enter to continue past the security notes and complete the setup. + + + +--- + +### Part 3: Use Claude Code with LiteLLM + +Now you can use Claude Code normally, and all requests will be tracked in LiteLLM. + +#### 3.1 Make a Request in Claude Code + +Start using Claude Code - requests will flow through LiteLLM Gateway. + + + +#### 3.2 View Logs in LiteLLM Dashboard + +Navigate to the Logs page in LiteLLM Dashboard to see all Claude Code requests. + + + +#### 3.3 View Request Details + +Click on a request to see detailed information including tokens, cost, duration, and model used. + + + +The logs show: +- **Key Name**: `claude-code-test` (the virtual key you created) +- **Model**: `anthropic/claude-sonnet-4-20250514` +- **Tokens**: 65012 (64679 prompt + 333 completion) +- **Cost**: $0.249754 +- **Status**: Success + + + +--- + +## How It Works + +LiteLLM Gateway handles two types of authentication: +1. **`x-litellm-api-key`**: Authenticates the request with LiteLLM (usage tracking, budgets, rate limits) +2. **OAuth Token (via `Authorization` header)**: Forwarded to Anthropic API for Claude Max authentication + +```mermaid +sequenceDiagram + participant User as Claude Code User + participant LiteLLM as LiteLLM AI Gateway + participant Anthropic as Anthropic API + + User->>LiteLLM: Request with:
- x-litellm-api-key (LiteLLM auth)
- Authorization: Bearer {oauth_token} + + Note over LiteLLM: 1. Validate x-litellm-api-key
2. Check budgets/rate limits
3. Log request for tracking + + LiteLLM->>Anthropic: Forward request with:
- Authorization: Bearer {oauth_token}
(User's Claude Max OAuth token) + + Note over Anthropic: Authenticate user via
OAuth token from Max plan + + Anthropic-->>LiteLLM: Response + + Note over LiteLLM: Log usage, tokens, cost + + LiteLLM-->>User: Response +``` + +### Header Flow + +| Header | Purpose | Handled By | +|--------|---------|------------| +| `x-litellm-api-key` | LiteLLM Gateway authentication, budget tracking, rate limits | LiteLLM | +| `Authorization: Bearer {oauth_token}` | Claude Max subscription authentication | Anthropic API | + +### Complete Request Flow Example + +Here's what a typical request looks like when Claude Code makes a call through LiteLLM: + +```bash showLineNumbers title="Example Request from Claude Code to LiteLLM" +curl -X POST "http://localhost:4000/v1/messages" \ + -H "x-litellm-api-key: Bearer sk-otsclFlEblQ-6D60ua2IZg" \ + -H "Authorization: Bearer oauth_token_from_max_plan" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "anthropic-claude", + "max_tokens": 1024, + "messages": [{"role": "user", "content": "Hello, Claude!"}] + }' +``` + +LiteLLM then: +1. Validates `x-litellm-api-key` for gateway access +2. Logs the request for usage tracking +3. Forwards the request to Anthropic with the OAuth `Authorization` header (because of `forward_client_headers_to_llm_api: true`) + +## Advanced Configuration + +### Per-Model Header Forwarding + +For more granular control, you can enable header forwarding only for specific models: + +```yaml showLineNumbers title="config.yaml - Per-Model Header Forwarding" +model_list: + - model_name: anthropic-claude + litellm_params: + model: anthropic/claude-sonnet-4-20250514 + + - model_name: claude-3-5-haiku-20241022 + litellm_params: + model: anthropic/claude-3-5-haiku-20241022 + +litellm_settings: + master_key: os.environ/LITELLM_MASTER_KEY + model_group_settings: + forward_client_headers_to_llm_api: + - anthropic-claude + - claude-3-5-haiku-20241022 +``` + +### Budget Controls + +Set up per-user budgets while using Max subscriptions: + +```yaml showLineNumbers title="config.yaml - With Database for Budget Tracking" +model_list: + - model_name: anthropic-claude + litellm_params: + model: anthropic/claude-sonnet-4-20250514 + +general_settings: + forward_client_headers_to_llm_api: true + database_url: "postgresql://..." + +litellm_settings: + master_key: os.environ/LITELLM_MASTER_KEY +``` + +Then create virtual keys with budgets: + +```bash showLineNumbers title="Create Virtual Key with Budget" +curl -X POST "http://localhost:4000/key/generate" \ + -H "Authorization: Bearer $LITELLM_MASTER_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "key_alias": "developer-1", + "max_budget": 100.00, + "budget_duration": "monthly" + }' +``` + +## Troubleshooting + +### OAuth Token Not Being Forwarded + +**Symptom**: Authentication errors from Anthropic API + +**Solution**: Ensure `forward_client_headers_to_llm_api: true` is set in your config: + +```yaml showLineNumbers title="config.yaml - Enable Header Forwarding" +general_settings: + forward_client_headers_to_llm_api: true +``` + +### LiteLLM Authentication Failing + +**Symptom**: 401 errors from LiteLLM Gateway + +**Solution**: Verify `x-litellm-api-key` header is set correctly in `ANTHROPIC_CUSTOM_HEADERS`: + +```bash showLineNumbers title="Verify Key Info" +curl -X GET "http://localhost:4000/key/info" \ + -H "Authorization: Bearer sk-otsclFlEblQ-6D60ua2IZg" +``` + +### Model Not Found + +**Symptom**: Model not found errors + +**Solution**: Ensure the `ANTHROPIC_MODEL` matches a model name in your config: + +```bash showLineNumbers title="List Available Models" +curl "http://localhost:4000/v1/models" \ + -H "Authorization: Bearer sk-otsclFlEblQ-6D60ua2IZg" +``` + +## Related Documentation + +- [Forward Client Headers](/docs/proxy/forward_client_headers) - Detailed header forwarding configuration +- [Claude Code Quickstart](/docs/tutorials/claude_responses_api) - Basic Claude Code + LiteLLM setup +- [Virtual Keys](/docs/proxy/virtual_keys) - Creating and managing API keys +- [Budgets & Rate Limits](/docs/proxy/users) - Setting up usage controls diff --git a/docs/my-website/img/claude_code_max.png b/docs/my-website/img/claude_code_max.png new file mode 100644 index 0000000000..65c9578a45 Binary files /dev/null and b/docs/my-website/img/claude_code_max.png differ diff --git a/docs/my-website/img/claude_code_max/step1.jpeg b/docs/my-website/img/claude_code_max/step1.jpeg new file mode 100644 index 0000000000..6b65d598d3 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step1.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step10.jpeg b/docs/my-website/img/claude_code_max/step10.jpeg new file mode 100644 index 0000000000..326f9b12d1 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step10.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step12.jpeg b/docs/my-website/img/claude_code_max/step12.jpeg new file mode 100644 index 0000000000..97199e9ead Binary files /dev/null and b/docs/my-website/img/claude_code_max/step12.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step13.jpeg b/docs/my-website/img/claude_code_max/step13.jpeg new file mode 100644 index 0000000000..53fd1c9bd5 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step13.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step14.jpeg b/docs/my-website/img/claude_code_max/step14.jpeg new file mode 100644 index 0000000000..5c3e4b05e2 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step14.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step15.jpeg b/docs/my-website/img/claude_code_max/step15.jpeg new file mode 100644 index 0000000000..2c63ba6e75 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step15.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step16.jpeg b/docs/my-website/img/claude_code_max/step16.jpeg new file mode 100644 index 0000000000..7abb53edb8 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step16.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step17.jpeg b/docs/my-website/img/claude_code_max/step17.jpeg new file mode 100644 index 0000000000..a9c352f85e Binary files /dev/null and b/docs/my-website/img/claude_code_max/step17.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step18.jpeg b/docs/my-website/img/claude_code_max/step18.jpeg new file mode 100644 index 0000000000..0177537fef Binary files /dev/null and b/docs/my-website/img/claude_code_max/step18.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step19.jpeg b/docs/my-website/img/claude_code_max/step19.jpeg new file mode 100644 index 0000000000..d84eec24dd Binary files /dev/null and b/docs/my-website/img/claude_code_max/step19.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step2.jpeg b/docs/my-website/img/claude_code_max/step2.jpeg new file mode 100644 index 0000000000..2d7255c73a Binary files /dev/null and b/docs/my-website/img/claude_code_max/step2.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step20.jpeg b/docs/my-website/img/claude_code_max/step20.jpeg new file mode 100644 index 0000000000..3e97cba38c Binary files /dev/null and b/docs/my-website/img/claude_code_max/step20.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step21.jpeg b/docs/my-website/img/claude_code_max/step21.jpeg new file mode 100644 index 0000000000..02387c7666 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step21.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step22.jpeg b/docs/my-website/img/claude_code_max/step22.jpeg new file mode 100644 index 0000000000..7aa920221d Binary files /dev/null and b/docs/my-website/img/claude_code_max/step22.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step23.jpeg b/docs/my-website/img/claude_code_max/step23.jpeg new file mode 100644 index 0000000000..4eb9c62c72 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step23.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step24.jpeg b/docs/my-website/img/claude_code_max/step24.jpeg new file mode 100644 index 0000000000..bb38c2e19a Binary files /dev/null and b/docs/my-website/img/claude_code_max/step24.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step25.jpeg b/docs/my-website/img/claude_code_max/step25.jpeg new file mode 100644 index 0000000000..fb1e095066 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step25.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step26.jpeg b/docs/my-website/img/claude_code_max/step26.jpeg new file mode 100644 index 0000000000..9eb418b9be Binary files /dev/null and b/docs/my-website/img/claude_code_max/step26.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step27.jpeg b/docs/my-website/img/claude_code_max/step27.jpeg new file mode 100644 index 0000000000..b8efb3aeb1 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step27.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step28.jpeg b/docs/my-website/img/claude_code_max/step28.jpeg new file mode 100644 index 0000000000..a2ce52441e Binary files /dev/null and b/docs/my-website/img/claude_code_max/step28.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step3.jpeg b/docs/my-website/img/claude_code_max/step3.jpeg new file mode 100644 index 0000000000..a5f28c8049 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step3.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step4.jpeg b/docs/my-website/img/claude_code_max/step4.jpeg new file mode 100644 index 0000000000..ec9ffa4deb Binary files /dev/null and b/docs/my-website/img/claude_code_max/step4.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step5.jpeg b/docs/my-website/img/claude_code_max/step5.jpeg new file mode 100644 index 0000000000..25d33f27a0 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step5.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step6.jpeg b/docs/my-website/img/claude_code_max/step6.jpeg new file mode 100644 index 0000000000..116f792eac Binary files /dev/null and b/docs/my-website/img/claude_code_max/step6.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step7.jpeg b/docs/my-website/img/claude_code_max/step7.jpeg new file mode 100644 index 0000000000..1a3b232d2b Binary files /dev/null and b/docs/my-website/img/claude_code_max/step7.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step8.jpeg b/docs/my-website/img/claude_code_max/step8.jpeg new file mode 100644 index 0000000000..1a67a135c3 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step8.jpeg differ diff --git a/docs/my-website/img/claude_code_max/step9.jpeg b/docs/my-website/img/claude_code_max/step9.jpeg new file mode 100644 index 0000000000..b95594e617 Binary files /dev/null and b/docs/my-website/img/claude_code_max/step9.jpeg differ diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index dc4d7ce619..9572fc9774 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -121,6 +121,7 @@ const sidebars = { label: "Claude Code", items: [ "tutorials/claude_responses_api", + "tutorials/claude_code_max_subscription", "tutorials/claude_code_customer_tracking", "tutorials/claude_code_websearch", "tutorials/claude_mcp",