Claude Code

Route the Claude Code CLI and VS Code extension through the TrueFoundry AI Gateway, with authentication for Enterprise, Team, Pro, and Max plans.

Claude Code is Anthropic’s agentic coding tool for the terminal and VS Code. It reads its API endpoint and credentials from environment variables in settings.json, which is what lets you point it at the TrueFoundry AI Gateway: every model call then passes through the gateway for cost tracking, rate and budget limits, access control, guardrails, and logging.

This page covers the CLI and the VS Code extension. For the desktop app see Claude Desktop; for claude.ai see Claude Web. If you just want to see it work on one machine, start with the quick start.

Want to guardrail Claude Code’s prompts and tool calls (not just model requests)? See Guardrails using Claude Code Hooks, it uses Claude Code hooks to block or rewrite dangerous actions in the client.

Prerequisites

1. TrueFoundry account, sign up and follow the Gateway quick start to get your gateway base URL and an API key.
2. Claude models on the gateway, add an Anthropic, Bedrock, or Vertex model account via Anthropic model integration. Include Opus, Sonnet, and Haiku so all of Claude Code’s aliases resolve.
3. Claude Code, install following the official documentation.

Integrate TrueFoundry with Claude Code

Get the base URL and a model name from the TrueFoundry playground’s unified code snippet:

Claude Code can be configured globally or per project:

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

Authentication and who pays

Every request Claude Code sends through the gateway carries two things: a TrueFoundry credential that tells the gateway who you are, and, on the way out, an Anthropic credential that tells Anthropic who pays. The gateway always gets the first one from you. Where the second one comes from is the only real configuration choice, and it has nothing to do with which Claude plan you’re on:

	API-key mode	Subscription passthrough
Who pays Anthropic	Your API key, per token	The user’s Claude seat or subscription, from its allowance
What’s in Authorization	Your TrueFoundry key	The user’s Claude login token, which the gateway forwards untouched
Where the TrueFoundry key goes	ANTHROPIC_AUTH_TOKEN	ANTHROPIC_CUSTOM_HEADERS as x-tfy-api-key, because Authorization is taken
Model account on TrueFoundry	Holds an Anthropic, Bedrock, or Vertex key	Empty: an empty key tells the gateway to forward the client’s Authorization
User logs in to Claude?	No. Anthropic never sees a user; the seat, if any, is untouched	Yes, /login once. Anthropic attributes usage to that seat
Requires	An API key, any plan, or no Claude plan at all	A plan that includes Claude Code: Enterprise or Team seats, or a Pro / Max subscription
Providers	Anthropic, Bedrock, Vertex, Foundry	Anthropic direct only
Gateway visibility	Full: per-user attribution, budgets, rate limits, guardrails, logs	Full: identical, via the TrueFoundry key
Typical reason	One org bill, cloud-provider routing, callers with no human (CI, service accounts, the Agent SDK), no seats	The org already pays for seats and wants them to do the work; personal Pro / Max users

If your users have seats, passthrough is the only way those seats pay for Claude Code traffic that goes through the gateway; API-key mode leaves them unused and bills your key on top. If they don’t, API-key mode is the only option. Enterprise orgs commonly run both: passthrough for developers on seats, API-key mode for pipelines and for Bedrock-routed workloads.

API-key mode

Create the Anthropic model account with your API key (see Anthropic model integration), then put your TrueFoundry key in ANTHROPIC_AUTH_TOKEN:

{
  "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"
  }
}

Replace {GATEWAY_BASE_URL} with your gateway base URL (how to find it), your-truefoundry-api-key with your key, and the model names with your configured models in provider-account/model-name format. No Claude login is involved: the gateway consumes the Authorization header, authenticates you, and calls the provider with the key stored on the model account. The user’s Claude plan, if they have one, is never touched.

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS disables experimental features in Claude Code for stable behavior with the AI Gateway.

Subscription passthrough

Create the Anthropic model account with the API key left empty (leave Anthropic API Key Auth disabled). An empty key is an instruction to the gateway: forward whatever Authorization header the client sent instead of supplying one. Claude Code puts the user’s Claude login token there, so Anthropic charges that user’s seat or subscription and attributes the usage to them.

Because Authorization is now carrying the Claude token, the TrueFoundry key moves to x-tfy-api-key. Leave ANTHROPIC_AUTH_TOKEN unset:

{
  "env": {
    "ANTHROPIC_BASE_URL": "{GATEWAY_BASE_URL}",
    "ANTHROPIC_CUSTOM_HEADERS": "x-tfy-api-key: your-truefoundry-api-key\nX-TFY-LOGGING-CONFIG: {\"enabled\": true}",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-code/claude-opus",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-code/claude-sonnet",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-code/claude-haiku"
  }
}

Or as environment variables:

export ANTHROPIC_BASE_URL="https://<your-gateway-base-url>"
export ANTHROPIC_CUSTOM_HEADERS="x-tfy-api-key: <your-truefoundry-api-key>"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-code/claude-opus"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-code/claude-sonnet"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-code/claude-haiku"
claude

Start Claude Code and run /login, choosing the account type that matches your plan (Claude Enterprise, Team, or your personal Pro/Max account). The token Claude Code receives is short-lived and refreshed by Claude Code itself; a 401 later usually means it expired, and /login fixes it.

The Authorization header is forwarded to Anthropic only when the model account has no API key. If a key is present the gateway uses it and ignores the client’s header, so the request is billed to the key, not the subscription. This is also why passthrough can’t be used for Claude Desktop: in third-party mode Desktop has no Claude login, so its Authorization header holds the TrueFoundry key, and forwarding that to Anthropic returns 401 Invalid bearer token.

A virtual model can have only one passthrough (empty-key) Anthropic target. The gateway forwards a single Authorization header, and it is only valid for the account the user signed in with. Other targets in the same virtual model must be API-key accounts.

Fall back from the subscription to the Anthropic API

A subscription covers most day-to-day Claude Code work, but when its limit is hit requests start failing mid-task. Route through a virtual model that uses the subscription first and falls back to a pay-per-token Anthropic account when the subscription is rate-limited. Work continues, and only the overflow is billed per token.

The setup uses two Anthropic accounts and one virtual model per Claude model:

• A subscription account (for example claude-pro-traffic) with no API key, the user’s Authorization header is forwarded to Anthropic.
• A standard account (for example anthropic-primary) with an Anthropic API key.
• A virtual model that targets the subscription account at priority 0 and the standard account as the lower-priority fallback.

1. Add the subscription account

   Create an Anthropic account with Anthropic API Key Auth disabled and add the Claude models you want to route through the subscription.

   
2. Add the standard Anthropic account

   Create a second Anthropic account (for example anthropic-primary) with Anthropic API Key Auth enabled and a valid API key. This is billed per token and serves as the fallback.

3. Create virtual models with priority-based fallback

   For each Claude model, create a virtual model with the subscription target at priority 0 and the standard target as the fallback. The gateway routes to the fallback only when the subscription target is rate-limited or unavailable.

   

   In the example above, the claude-opus virtual model routes to claude-pro-traffic/claude-opus-4-8 first and falls back to anthropic-primary/claude-opus-4-8; the same pattern applies to Sonnet and Haiku.

4. Point Claude Code at the virtual models

   Set ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL to the virtual model names. Claude Code talks to one endpoint while the gateway handles the subscription-to-API fallback.

Controlling fast mode on subscriptions

Users on a subscription can turn on fast mode per request with /fast or globally in their config. Fast mode uses significantly more of the subscription allowance, so you may want to control it centrally. Create two virtual models, one that strips fast mode and one that allows it, and hand out the appropriate model name.

Virtual model 1: fast mode disabled. Route to claude-opus-4-6 and configure the virtual model to delete the speed field from the request body, so requests always go through as standard requests even if the user enabled fast mode.

Virtual model 2: fast mode allowed. Route to claude-opus-4-6 with no additional parameters or headers, so a user’s fast-mode setting reaches Anthropic.

Then use the appropriate virtual model name in ANTHROPIC_MODEL and ANTHROPIC_DEFAULT_OPUS_MODEL.

For a fleet, tfy-local-ai-setup writes either configuration into a locked managed-settings.json with a per-user TrueFoundry token, see Enforce with MDM. For how the same choice plays out on Claude Desktop (API-key mode only) and claude.ai (seat only), see the overview.

Verify the integration

Start Claude Code and send a prompt. Run /model to confirm the picker shows your gateway models, then open AI Gateway → Analytics in TrueFoundry: the request appears under your user with its model, token counts, and cost, and Request Logs shows the prompt and response. See Analytics overview and Request logging. On subscription passthrough the cost figure is an estimate at API list price; the seat is what actually pays.

Model configuration

Claude Code has built-in model aliases (opus, sonnet, haiku, opusplan) that users switch between with /model opus, --model sonnet, and so on. The ANTHROPIC_DEFAULT_*_MODEL variables map each alias to a model on your gateway:

• ANTHROPIC_DEFAULT_OPUS_MODEL, the opus alias
• ANTHROPIC_DEFAULT_SONNET_MODEL, the sonnet alias
• ANTHROPIC_DEFAULT_HAIKU_MODEL, the haiku alias

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

Forwarding Anthropic beta features

Anthropic releases beta features (e.g. context management) that require the anthropic-beta header on API requests. To forward a beta flag through the AI Gateway, set the x-tfy-anthropic-beta header via ANTHROPIC_CUSTOM_HEADERS as shown in the baseline config. To enable multiple beta features, pass them as a comma-separated list (no spaces):

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

Beta support depends on the routed provider. For direct Anthropic requests, Anthropic validates the beta identifier. For AWS Bedrock, Bedrock Mantle, and Google Vertex AI, the Gateway translates supported identifiers and omits identifiers that the provider does not accept.

x-tfy-anthropic-beta is a gateway-specific header that is mapped to the outbound anthropic-beta header. When it is present, it replaces Claude Code’s own anthropic-beta header, body anthropic_beta, and any other client beta source, the values are not merged. A virtual model can override it only by setting x-tfy-anthropic-beta in headers_override; setting anthropic-beta there does not replace it.

VS Code extension

The Claude Code VS Code extension reuses the CLI’s configuration, base URL, credentials, and model aliases, so there is no separate setup.

The extension is not standalone. Install and configure the CLI first.

1. Configure the CLI as described above.
2. Install the VS Code extension.
3. On macOS and Linux, launch VS Code from the terminal where Claude Code is configured (code .), since GUI applications don’t inherit shell environment variables by default. Settings in ~/.claude/settings.json are picked up regardless.

Guardrails

Three layers can inspect Claude Code traffic, and they stack:

• Gateway guardrails run on every model request that passes through the gateway: input and output checks, PII, prompt injection, moderation, and request logs for audit. Configure them once on the gateway; nothing to set in Claude Code. See Guardrails overview.
• Claude Code hooks reach what the model request never shows: prompt submissions, shell commands, file edits, and MCP tool calls. A hook posts each event to the gateway, which can block it or rewrite the tool input or output. Configured in settings.json and enforceable through managed-settings.json.
• Anthropic Inference Hooks (Enterprise only) are configured in Anthropic’s admin console and cover every Claude surface at once, including Claude Code sessions that don’t go through the gateway. Allow/deny only.

MCP servers and web search

Route the MCP servers Claude Code uses through the TrueFoundry MCP Gateway so tool access is allowlisted, authenticated, and audited centrally. This includes web search: Claude Code’s built-in search is an Anthropic server-side tool that only works when the routed provider executes it, so for search that behaves the same on every model, add a web-search MCP server (Tavily, Exa) behind the gateway instead.

Setup for both, including managed-mcp.json for fleet rollout and how to disable the built-in WebSearch tool, is on Govern MCP traffic.

FAQs

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:

{
  "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 AI Gateway stays the same.

How do I use Claude Opus 4.6 Fast Mode with the AI Gateway?

Claude Opus 4.6 supports a fast mode that provides lower-latency responses. To use it through the TrueFoundry AI 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.

Step 2: Add the speed parameter

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

{
  "speed": "fast"
}

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

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:

anthropic-beta: fast-mode-2026-02-01

If the client also sends x-tfy-anthropic-beta (for example via ANTHROPIC_CUSTOM_HEADERS), a virtual-model anthropic-beta override will not replace it. Set x-tfy-anthropic-beta on the virtual model instead, and include every token you want sent (including fast-mode-2026-02-01).

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:

{
  "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.

Does the Claude Agent SDK pick up this configuration?

Yes. The Claude Agent SDK (successor to the deprecated Claude Code SDK) no longer reads filesystem settings automatically, so pass setting_sources=["project"] to load .claude/settings.json:

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 TrueFoundry configurations (Anthropic direct, AWS Bedrock, Google Vertex AI) work identically with the SDK.

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 AI 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 for setup, the validation-vs-mutation capability matrix, and caveats.

Do I need CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1? Which beta headers reach the model?

Not on an Anthropic-direct route; set it to 0 if you want Claude Code’s newer features. Forward specific betas with "ANTHROPIC_CUSTOM_HEADERS": "x-tfy-anthropic-beta: <value>,<value>". x-tfy-anthropic-beta replaces, rather than merges with, a raw anthropic-beta header.

On Anthropic /v1/messages there is no allowlist: beta values, safeguards, tool_reference, defer_loading, and thinking blocks pass through. On Bedrock, Vertex, and Foundry the gateway filters betas against a per-provider allowlist and silently drops unsupported ones, so a feature such as tool search may not run there. To see what was forwarded, check the trace attributes tfy.model.anthropic_betas_requested and tfy.model.anthropic_betas_sent. Note that DISABLE_EXPERIMENTAL_BETAS=1 also overrides ENABLE_TOOL_SEARCH=TRUE. See Forwarding Anthropic beta features.

Claude Code returns 403 'not authorized to access model … or model does not exist'

The slug Claude Code sent doesn’t match a gateway model this user can access. Check three things: the provider-account/model-name values in ANTHROPIC_MODEL and the ANTHROPIC_DEFAULT_*_MODEL variables are spelled exactly as the gateway lists them; none of them is missing (a slug ending in /undefined means an env var is unset); and the user has been granted the model. To populate the picker from the gateway instead of hardcoding, set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1; the gateway serves /v1/models. On a self-hosted gateway, ANTHROPIC_BASE_URL ends at /api/llm, not /api/llm/v1. See Model configuration.

Claude Code asks for a model ending in [1m] and the gateway rejects it

Append [1m] to the model name in settings.json (for example claude-code/claude-sonnet[1m]). Claude Code strips the suffix before sending and treats the model as the 1M-context variant internally, so the gateway sees the normal model name. Don’t create a model with brackets in its name on the gateway; brackets aren’t allowed in integration names. See the Claude Code FAQ.

Claude Code's auto mode or classifier behaves differently through the gateway

First upgrade Claude Code. Several reported differences on the subscription-passthrough route were client bugs fixed in later releases. If a current client still misbehaves, open a ticket with the trace attributes tfy.model.anthropic_betas_requested and tfy.model.anthropic_betas_sent from a failing request, the virtual model configuration, and the settings.json env block.