> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> How to connect Claude Code with the TrueFoundry AI Gateway.

This guide provides instructions for integrating [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with the Truefoundry AI Gateway.

<Note>
  This page covers the **Claude Code CLI** and the **VS Code extension**, which use `ANTHROPIC_BASE_URL` and environment variables in `settings.json`. For the other two Claude surfaces, see the overview below — **[Claude Desktop](/docs/ai-gateway/claude-desktop)** (Cowork on third-party inference) and **claude.ai** (the web app).
</Note>

<Tip>
  Want to guardrail Claude Code's **prompts and tool calls** (not just model requests)? See **[Guardrails using Claude Code Hooks](/docs/ai-gateway/claude-code-hooks)** — it uses Claude Code hooks to block or rewrite dangerous actions in the client.
</Tip>

## The Claude surfaces you can govern

TrueFoundry can put every Claude surface — not just the CLI — behind the AI Gateway, with fleet-wide enforcement via MDM where the tool supports it:

| Surface                         | How it routes to the gateway                                                                             |        MDM-enforceable        | Guide                                                                                                                       |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- | :---------------------------: | --------------------------------------------------------------------------------------------------------------------------- |
| **Claude Code (CLI + VS Code)** | `ANTHROPIC_BASE_URL` in `managed-settings.json`                                                          | Yes (macOS · Linux · Windows) | This page                                                                                                                   |
| **Claude Desktop (Cowork 3P)**  | `com.anthropic.claudefordesktop` managed preferences                                                     |     Yes (macOS · Windows)     | [Claude Desktop](/docs/ai-gateway/claude-desktop)                                                                           |
| **claude.ai (web app)**         | On-device interception with [aitori](https://github.com/truefoundry/aitori) — no endpoint setting exists |        Deployed via MDM       | [Govern all AI traffic](/docs/ai-gateway/govern-traffic-through-ai-gateway#method-b-aitori-the-open-source-on-device-agent) |

**Claude Code and Claude Desktop** are configured by the same tool: TrueFoundry ships the **[`tfy-local-ai-setup`](https://github.com/truefoundry/tfy-local-ai-setup)** binary, deployed over MDM, which runs the device-login flow, writes the managed config (with a fresh gateway token in the `X-TFY-API-KEY` header), immutably locks it, and refreshes on a schedule. Prebuilt binaries for all platforms live on the [releases page](https://github.com/truefoundry/tfy-local-ai-setup/releases). One run configures whichever tools are installed — pass `--claude-code`, `--claude-desktop`, and `--codex`, or omit all three to auto-detect. See [Enterprise security with MDM](/docs/ai-gateway/mcp/enterprise-security-claude) for the full deployment scripts.

**claude.ai** has no endpoint setting — the web app calls Anthropic's backend directly — so it can't be pointed at a gateway the way the CLI or Desktop can. To govern it, TrueFoundry ships **[aitori](https://github.com/truefoundry/aitori)**, an open-source (Apache-2.0) on-device agent that runs as the machine's HTTPS proxy, decrypts an allowlist of AI hosts, and reroutes their model and MCP calls through the gateway. Try it on one machine:

```bash theme={"dark"}
# Install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/truefoundry/aitori/main/install.sh | sh

# Govern this machine and open the live view at http://127.0.0.1:9100
sudo aitori up --ui \
  --gateway-url "https://gateway.truefoundry.ai/api/llm/ai-proxy/" \
  --token-file ~/.aitori/tf_token

# Revert the system proxy when you're done
sudo aitori down
```

Claude (Code, Desktop, web) and ChatGPT are covered by built-in profiles, so there are no rules to write to get started. Because claude.ai calls Anthropic's backend server-side, you get guardrails and audit on the visible content but **not** token-level cost tracking. Full setup, config-file rollout, and the fleet story are in [Govern all AI traffic through the gateway](/docs/ai-gateway/govern-traffic-through-ai-gateway).

## What is Claude Code?

Claude Code is Anthropic's agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster through natural language commands. It serves as an intelligent pair programming partner that can read, analyze, and work with your entire project structure.

## Model Configuration

Claude Code supports model aliases (`opus`, `sonnet`, `haiku`, `opusplan`) that provide convenient shortcuts for different use cases. When integrating with TrueFoundry, you can configure these aliases to use your specific TrueFoundry models through environment variables.

<Note>
  Model aliases allow you to switch between different Claude models during your coding session using simple commands like `/model opus` or `/model sonnet`.
</Note>

## Prerequisites

Before integrating Claude Code with TrueFoundry, ensure you have:

1. **TrueFoundry Account**: Create a [Truefoundry account](https://www.truefoundry.com/register) and follow the instructions in our [Gateway Quick Start Guide](https://docs.truefoundry.com/gateway/quick-start)
2. **Claude Code Installation**: Install Claude Code following the [official documentation](https://docs.anthropic.com/en/docs/claude-code)
3. Configure models in Truefoundry for each provider you want to use

## Integrate Truefoundry with Claude Code

Claude Code uses a settings.json file for configuration. You'll need to modify the environment variables to route requests through Truefoundry.

First, get the base URL and model name from your TrueFoundry AI Gateway playground using the unified code snippet:

<Frame>
  <img src="https://mintcdn.com/truefoundry/n3EuZuJ0K8wBFp1G/images/new-code-snippet.png?fit=max&auto=format&n=n3EuZuJ0K8wBFp1G&q=85&s=3634c2dc8c3565fd77ab896d3fd07ed9" alt="TrueFoundry playground showing unified code snippet with base URL and model name" width="2940" height="1664" data-path="images/new-code-snippet.png" />
</Frame>

Claude Code can be configured either globally or per project by editing the settings file:

* Global: `~/.claude/settings.json`
* Project-specific: `.claude/settings.json` in your project directory

```json lines theme={"dark"}
{
  "env": {
    "ANTHROPIC_BASE_URL": "{GATEWAY_BASE_URL}",
    "ANTHROPIC_AUTH_TOKEN": "your-truefoundry-api-key",
    "ANTHROPIC_MODEL": "claude-code/claude-sonnet",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-code/claude-opus",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-code/claude-sonnet",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-code/claude-haiku",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_CUSTOM_HEADERS": "x-tfy-anthropic-beta: context-management-2025-06-27"
  }
}
```

<Note>
  `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` disables experimental features in Claude Code for stable behavior with TrueFoundry Gateway.
</Note>

<Note>
  Claude Code detects model capabilities (e.g. extended thinking `effort`, ToolSearch, beta tool blocks) by string-matching the model id. Make sure the value of `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` contains a recognizable Anthropic model id like `claude-opus-4-7`, `claude-sonnet-4-6`, or `claude-haiku-4-5` or `claude-haiku-4-5-20251001`. If you're using a TrueFoundry virtual model, ensure that the virtual model's display name is the same as the underlying Anthropic model id (e.g. `claude-haiku-4-5`), so the full value `your-account/claude-haiku-4-5` contains a recognizable id for Claude Code; otherwise Claude Code may attach parameters the underlying model doesn't support and Anthropic will return `400: This model does not support the effort parameter`.
</Note>

### Forwarding Anthropic Beta Features

Anthropic releases beta features (e.g. [context management](https://docs.anthropic.com/en/docs/build-with-claude/context-editing)) that require the `anthropic-beta` header on API requests. To forward a beta flag through the TrueFoundry Gateway, set the `x-tfy-anthropic-beta` header via `ANTHROPIC_CUSTOM_HEADERS` as shown in the config above.

To enable multiple beta features, pass them as a comma-separated list (no spaces):

```json theme={"dark"}
{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "x-tfy-anthropic-beta: context-management-2025-06-27,files-api-2025-04-14"
  }
}
```

<Note>
  Use exact beta feature names as documented by [Anthropic](https://docs.anthropic.com/en/api/beta-headers). Invalid beta names will return a `400` error from the Anthropic API.
</Note>

<Tip>
  `x-tfy-anthropic-beta` is a gateway-specific header that gets mapped to the `anthropic-beta` header on the outbound request to Anthropic. This avoids conflicts with Claude Code's own `anthropic-beta` header.
</Tip>

## Using Claude Code VS Code Extension

The [Claude Code VS Code extension](https://marketplace.visualstudio.com/items?itemName=Anthropic.claude-code) works seamlessly with TrueFoundry once you've configured the CLI.

<Warning>
  The VS Code extension is **not standalone**. It requires the Claude Code CLI to be installed separately and configured first.
</Warning>

**Setup Steps:**

1. Install and configure the Claude Code CLI as described [above](#integrate-truefoundry-with-claude-code)
2. Install the VS Code extension
3. Launch VS Code from your terminal to inherit the configuration:

```bash lines theme={"dark"}
code .
```

<Note>
  The extension automatically uses your CLI configuration (base URL, API keys, model aliases). No separate setup needed.
</Note>

**Important for macOS/Linux:** Launch VS Code from the terminal where you've set up Claude Code. GUI applications don't inherit shell environment variables by default.

### Model Alias Configuration

The following environment variables map Claude Code's built-in aliases to your TrueFoundry models:

* `ANTHROPIC_DEFAULT_OPUS_MODEL`: Maps `opus` alias to your TrueFoundry Opus model
* `ANTHROPIC_DEFAULT_SONNET_MODEL`: Maps `sonnet` alias to your TrueFoundry Sonnet model
* `ANTHROPIC_DEFAULT_HAIKU_MODEL`: Maps `haiku` alias to your TrueFoundry Haiku model

**Benefits:** Model aliases enable seamless integration with Claude Code's built-in commands, flexible model switching with `/model opus` or `/model sonnet`, and optimized workflows by choosing the right model for each task.

### Example Usage

```bash lines theme={"dark"}
# Use different models for different tasks
claude --model opus "Design a scalable microservices architecture"
claude --model sonnet "Implement a user authentication system"
claude --model haiku "Write a function to validate email addresses"

# Switch models during a session
/model opusplan  # Uses opus for planning, sonnet for execution
```

## Claude Agent SDK

The [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) is the successor to the Claude Code SDK, providing programmatic access to build custom AI agents with the same capabilities as Claude Code.

<Note>
  The Claude Code SDK has been deprecated. If you're using the old SDK, migrate to the Claude Agent SDK for continued support and new features.
</Note>

### Installation

```bash theme={"dark"}
pip install claude-agent-sdk
```

### Key Changes from Claude Code SDK

**What changed:** The SDK no longer reads from filesystem settings automatically. You must explicitly specify which settings to load.

**Manual setup required:** You now need to explicitly load settings for:

* Settings files (`.claude/settings.json` for project, `~/.claude/settings.json` for user)
* `CLAUDE.md` files (project memory)
* Custom slash commands from `.claude/commands/`

### TrueFoundry Integration

Your existing `.claude/settings.json` configuration works seamlessly with the Agent SDK. Simply specify `setting_sources=["project"]` to load your TrueFoundry gateway configuration:

```python theme={"dark"}
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Analyze my codebase",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads .claude/settings.json
        max_turns=5,
        allowed_tools=["Read", "Grep", "Glob"]
    )
):
    if message.type == "result":
        print(message.result)
```

All your existing TrueFoundry configurations (`Anthropic Direct`, `AWS Bedrock`, `Google Vertex AI`) work identically with the Agent SDK.

## FAQs

<AccordionGroup>
  <Accordion title="How do I use the 1M (1 million) context window variant?">
    Some Claude models (e.g. Opus and Sonnet) offer a **1 million token context window** variant. To use it in Claude Code, just append `[1m]` to the end of the model name in your `settings.json`:

    ```json theme={"dark"}
    {
      "env": {
        "ANTHROPIC_MODEL": "claude-code/claude-sonnet[1m]"
      }
    }
    ```

    You **do not** need to create a separate model with `[1m]` in its name on TrueFoundry. Claude Code handles the suffix internally — it strips `[1m]` before sending the request and still treats it as the 1M context variant, so the underlying model on the gateway stays the same.
  </Accordion>

  <Accordion title="How do I use Claude Opus 4.6 Fast Mode with the Gateway?">
    Claude Opus 4.6 supports a **fast mode** that provides lower-latency responses. To use it through the TrueFoundry Gateway, you need to create a virtual model with the correct additional parameters and headers.

    **Step 1: Create a Virtual Model**

    Create a virtual model in TrueFoundry that routes all traffic to `claude-opus-4-6`. In the virtual model configuration, set it to forward requests to your underlying `claude-opus-4-6` model.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/9Bc3RHdMcCcbhtTP/images/Screenshot-2026-04-20-at-4.55.12-PM-1.png?fit=max&auto=format&n=9Bc3RHdMcCcbhtTP&q=85&s=2ff2adb77a0164e2b3dd588c481275ee" alt="Screenshot 2026 04 20 At 4 55 12 PM 1" width="3596" height="2006" data-path="images/Screenshot-2026-04-20-at-4.55.12-PM-1.png" />
    </Frame>

    **Step 2: Add the `speed` parameter**

    In the virtual model's additional parameters, add the following field:

    ```json theme={"dark"}
    {
      "speed": "fast"
    }
    ```

    This ensures every request sent through this virtual model includes the `speed: fast` parameter.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/9Bc3RHdMcCcbhtTP/images/Screenshot-2026-04-20-at-4.54.54-PM-1.png?fit=max&auto=format&n=9Bc3RHdMcCcbhtTP&q=85&s=c5c81fe9eb18004f424bcb0eb1d94d19" alt="Screenshot 2026 04 20 At 4 54 54 PM 1" width="3590" height="2012" data-path="images/Screenshot-2026-04-20-at-4.54.54-PM-1.png" />
    </Frame>

    **Step 3: Add the required beta header**

    Fast mode requires the `anthropic-beta` header with the value `fast-mode-2026-02-01`. Add this as an additional header in the virtual model configuration:

    ```text theme={"dark"}
    anthropic-beta: fast-mode-2026-02-01
    ```

    <Frame>
      <img src="https://mintcdn.com/truefoundry/9Bc3RHdMcCcbhtTP/images/Screenshot-2026-04-20-at-4.54.45-PM-1.png?fit=max&auto=format&n=9Bc3RHdMcCcbhtTP&q=85&s=e37c3157b8e906a0ad66da253575efdc" alt="Screenshot 2026 04 20 At 4 54 45 PM 1" width="3600" height="2006" data-path="images/Screenshot-2026-04-20-at-4.54.45-PM-1.png" />
    </Frame>

    **Step 4: Use the virtual model in Claude Code**

    Once the virtual model is created, use its model name in your `settings.json`. Replace the `ANTHROPIC_MODEL` and the relevant alias (e.g. `ANTHROPIC_DEFAULT_OPUS_MODEL`) with the virtual model name:

    ```json theme={"dark"}
    {
      "env": {
        "ANTHROPIC_BASE_URL": "{GATEWAY_BASE_URL}",
        "ANTHROPIC_AUTH_TOKEN": "your-truefoundry-api-key",
        "ANTHROPIC_MODEL": "your-fast-opus-virtual-model-name",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "your-fast-opus-virtual-model-name",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "your-sonnet-model-name",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "your-haiku-model-name",
        "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
      }
    }
    ```

    When selecting a model in Claude Code (via `/model` or the `--model` flag), choose the virtual model name you configured above. All requests will automatically include the fast mode parameter and the required beta header.
  </Accordion>

  <Accordion title="How do I control Fast Mode on the Pro plan?">
    Users can enable fast mode in Claude Code — either per-request with `/fast` or globally in their config so all requests use fast mode. Since fast mode uses significantly more credits, you may want to control when it's used. Create two `virtual models` — one that disables fast mode and one that allows it — then hand out the appropriate model ID to users.

    **Virtual Model 1: Fast mode disabled (strip `speed`)**

    Create a virtual model that routes to `claude-opus-4-6` and configure it to delete the `speed` field from the request body. This ensures requests always go through as standard, non-fast requests — even if the user has fast mode enabled.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/9Bc3RHdMcCcbhtTP/images/Screenshot-2026-04-20-at-5.27.02-PM.png?fit=max&auto=format&n=9Bc3RHdMcCcbhtTP&q=85&s=e1066571415c17ff996aff9a945c0f86" alt="Screenshot 2026 04 20 At 5 27 02 PM" width="3592" height="2004" data-path="images/Screenshot-2026-04-20-at-5.27.02-PM.png" />
    </Frame>

    **Virtual Model 2: Fast mode allowed**

    Create a second virtual model that routes to `claude-opus-4-6` with no additional parameters or headers. This model passes requests through as-is, so when a user enables fast mode, it will reach Anthropic.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/9Bc3RHdMcCcbhtTP/images/Screenshot-2026-04-20-at-5.27.28-PM.png?fit=max&auto=format&n=9Bc3RHdMcCcbhtTP&q=85&s=61d0e8fa41240e87362f219f383baed1" alt="Screenshot 2026 04 20 At 5 27 28 PM" width="3596" height="1998" data-path="images/Screenshot-2026-04-20-at-5.27.28-PM.png" />
    </Frame>

    Then use the appropriate virtual model name in `settings.json`:

    ```json theme={"dark"}
    {
      "env": {
        "ANTHROPIC_BASE_URL": "{GATEWAY_BASE_URL}",
        "ANTHROPIC_AUTH_TOKEN": "your-truefoundry-api-key",
        "ANTHROPIC_MODEL": "your-virtual-model-name",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "your-virtual-model-name",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "your-sonnet-model-name",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "your-haiku-model-name",
        "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
      }
    }
    ```
  </Accordion>

  <Accordion title="Can I run guardrails on Claude Code's prompts and tool calls?">
    Yes. Beyond model requests, you can guardrail Claude Code's **prompt submissions and tool calls** using Claude Code hooks that post to the gateway's `POST /hooks/claude-code` endpoint. A violation blocks the prompt or tool call — or rewrites it — directly in the client. See [Guardrails using Claude Code Hooks](/docs/ai-gateway/claude-code-hooks) for setup, the validation-vs-mutation capability matrix, and caveats.
  </Accordion>
</AccordionGroup>