If you have AWS credentials and want to start using Claude Code through Amazon Bedrock, the login wizard walks you through it. You complete the AWS-side prerequisites once per account; the wizard handles the Claude Code side.
1
Enable Anthropic models in your AWS account
In the Amazon Bedrock console, open the Model catalog, select an Anthropic model, and submit the use case form. Access is granted immediately after submission. See Submit use case details for AWS Organizations and IAM configuration for the permissions your role needs.
2
Start Claude Code and choose Amazon Bedrock
Run claude. At the login prompt, select 3rd-party platform, then Amazon Bedrock. If you're already signed in and see the chat prompt instead, run /setup-bedrock to open the wizard. The command works when typed even though it isn't listed in the command menu until Bedrock is configured.
3
Follow the wizard prompts
Choose how you authenticate to AWS: an AWS profile detected from your ~/.aws directory, an Amazon Bedrock API key, an access key and secret, or credentials already in your environment. The wizard picks up your region, verifies which Claude models your account can invoke, and lets you pin them. It saves the result to the env block of your user settings file, so you don't need to export environment variables yourself.
After you've signed in, run /setup-bedrock any time to reopen the wizard and change your credentials, region, or model pins. The model pin step starts from your currently pinned models. The wizard writes to ~/.claude/settings.json, or to $CLAUDE_CONFIG_DIR/settings.json when CLAUDE_CONFIG_DIR is set.
Set up manually
To configure Amazon Bedrock through environment variables instead of the wizard, for example in CI or a scripted enterprise rollout, follow the steps below.
1. Submit use case details
First-time users of Anthropic models are required to submit use case details before invoking a model. This is done once per AWS account.
Ensure you have the right IAM permissions described below
Complete the use case form. Access is granted immediately after submission.
If you use AWS Organizations, you can submit the form once from the management account using the PutUseCaseForModelAccess API. This call requires the bedrock:PutUseCaseForModelAccess IAM permission. Approval extends to child accounts automatically.
2. Configure AWS credentials
Claude Code uses the default AWS SDK credential chain. Set up your credentials using one of these methods:
Claude Code requests role credentials from the IAM Identity Center region named by the profile's sso_region, which doesn't need to match the region you run Amazon Bedrock in. {/* min-version: 2.1.208 */}In v2.1.207, the Amazon Bedrock region overrode sso_region, so a profile whose IAM Identity Center instance is in a different region failed to authenticate with a Session token not found or invalid error.
Claude Code resolves the AWS default credential provider chain once and keeps the resolved credentials in memory. It reuses them until five minutes before they expire, or for one hour when they carry no expiration, so an SSO-backed profile requests credentials from IAM Identity Center about once per credential lifetime. A credential error from the API clears the cache, and the retry resolves fresh credentials.
Before v2.1.207, Claude Code resolved the chain on every API request, so an SSO-backed profile requested fresh credentials from IAM Identity Center each time and could be throttled in large deployments.
The cache covers every credential option above except an Amazon Bedrock API key, which doesn't use the provider chain. To resolve the chain on every request instead, set CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1.
Each resolve of the chain times out after 60 seconds. If a step in the chain stalls, for example a credential_process helper that waits for input it can't receive, the request fails with AWS default-chain credential resolve timed out. If your chain runs an interactive sign-in that legitimately needs longer, such as browser-based SSO with MFA through a wrapper like aws-vault, raise the limit in milliseconds with CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS. Before v2.1.207, a stalled credential resolution left the request waiting indefinitely.
Advanced credential configuration
Claude Code supports automatic credential refresh for AWS SSO and corporate identity providers. Add these settings to your Claude Code settings file (see Settings for file locations).
These two settings have different trigger conditions:
awsAuthRefresh: runs only when Claude Code detects that your AWS credentials are expired, either locally based on their timestamp or when the API returns a credential error, then retries the request with refreshed credentials.
awsCredentialExport: runs at session start and on each credential reload, even when the credentials in your AWS default credential provider chain are still valid. Use this when your Amazon Bedrock account requires cross-account credentials that differ from the ones the default provider chain would resolve.
awsAuthRefresh: Use this for commands that modify the .aws directory, such as updating credentials, SSO cache, or config files. The command's output is displayed to the user, but interactive input isn't supported. This works well for browser-based SSO flows where the CLI displays a URL or code and you complete authentication in the browser.
awsCredentialExport: Only use this if you can't modify .aws and must directly return credentials. This command runs whenever credentials need to be refreshed, not only when credentials are expired. Output is captured silently and not shown to the user. The command must output JSON in this format:
{/* min-version: 2.1.181 */}As of Claude Code v2.1.181, the flat output from aws configure export-credentials --format process is also accepted, with the same keys at the top level instead of nested under Credentials.
Expiration is optional. {/* min-version: 2.1.176 */}As of Claude Code v2.1.176, when the command returns a valid ISO 8601 Expiration, Claude Code caches the credentials until five minutes before that time. Without it, or on earlier versions, credentials are cached for one hour.
When you configure awsCredentialExport without awsAuthRefresh, Claude Code uses the exported credentials directly and doesn't re-resolve the AWS default credential provider chain at startup. Before v2.1.206, startup also re-resolved the default provider chain, which made a live SSO or STS call outside your proxy configuration and could block the first prompt for several minutes on networks with restricted egress.
3. Configure Claude Code
Set the following environment variables to enable Amazon Bedrock:
# Enable Bedrock integrationexport CLAUDE_CODE_USE_BEDROCK=1export AWS_REGION=us-east-1# optional if your AWS profile already sets a region# Optional: Override the AWS region for the small/fast model (Bedrock and Mantle).# On Bedrock, has no effect without ANTHROPIC_DEFAULT_HAIKU_MODEL# or the deprecated ANTHROPIC_SMALL_FAST_MODEL set.export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2# Optional: Override the Bedrock endpoint URL for custom endpoints or gateways# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com
When enabling Amazon Bedrock for Claude Code, keep the following in mind:
{/* min-version: 2.1.172 */}As of v2.1.172, you only need to set AWS_REGION to override your AWS profile's region or when your profile has no region. Claude Code resolves the region in this order:
AWS_REGION
AWS_DEFAULT_REGION
the region set on your active AWS profile, read from the AWS shared credentials file first and then the shared config file, matching AWS SDK precedence
us-east-1
The active profile is AWS_PROFILE if set, otherwise default. Set AWS_SHARED_CREDENTIALS_FILE or AWS_CONFIG_FILE to point at non-default file paths. Run /status to see the resolved region. When the region came from your AWS config files or the default fallback, /status also notes the source. On v2.1.171 and earlier, Claude Code does not read the AWS config files, so set AWS_REGION explicitly.
When using Amazon Bedrock, the /logout command is unavailable since authentication is handled through AWS credentials.
You can use settings files for environment variables like AWS_PROFILE that you don't want to leak to other processes. See Settings for more information.
4. Pin model versions
Set these environment variables to specific Amazon Bedrock model IDs.
Without ANTHROPIC_DEFAULT_OPUS_MODEL, the opus alias on Amazon Bedrock resolves to Opus 5, and without ANTHROPIC_DEFAULT_SONNET_MODEL, the sonnet alias resolves to Sonnet 4.5. This example pins each alias to a specific version:
These variables use cross-region inference profile IDs (with the us. prefix). If you use a different region prefix or application inference profiles, adjust accordingly. In AWS GovCloud regions, use the us-gov. prefix. For current and legacy model IDs, see Models overview. See Model configuration for the full list of environment variables.
Claude Code uses these default models when no pinning variables are set:
Model type
Default value
Primary model
us.anthropic.claude-opus-5
Small/fast model
us.anthropic.claude-sonnet-4-5-20250929-v1:0
Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Amazon Bedrock, Claude Code uses the default Sonnet model for background tasks because Haiku may not be enabled in every account or region. Two selections change which model carries them:
When you select a primary model with --model, ANTHROPIC_MODEL, or the model setting, background tasks use that model. Setting ANTHROPIC_DEFAULT_OPUS_MODEL without ANTHROPIC_DEFAULT_SONNET_MODEL counts as a selection too, because the built-in Sonnet model may not be enabled in an account that steers its own Opus.
To use Haiku for background tasks, set ANTHROPIC_DEFAULT_HAIKU_MODEL to a model ID that is available in your account.
{/* min-version: 2.1.219 /}On v2.1.207 through v2.1.218, the primary model on Amazon Bedrock defaulted to Opus 4.8 and the opus alias resolved to Opus 4.8. {/ min-version: 2.1.207 */}Before v2.1.207, the primary model defaulted to Sonnet 4.5, the opus alias resolved to Opus 4.6, and background tasks always used the primary model.
To customize models further, use one of these methods:
# Using inference profile IDexport ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'# Using application inference profile ARNexport ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'# Optional: Disable prompt caching if needed# export DISABLE_PROMPT_CACHING=1# Optional: Request 1-hour prompt cache TTL instead of the 5-minute default# export ENABLE_PROMPT_CACHING_1H=1
The 1-hour cache TTL is billed at a higher rate than the 5-minute default. See cache lifetime.
Map each model version to an inference profile
The ANTHROPIC_DEFAULT_*_MODEL environment variables configure one inference profile per model family. If your organization needs to expose several versions of the same family in the /model picker, each routed to its own application inference profile ARN, use the modelOverrides setting in your settings file instead.
This example maps four Opus versions to distinct ARNs so users can switch between them without bypassing your organization's inference profiles:
When a user selects one of these versions in /model, Claude Code calls Amazon Bedrock with the mapped ARN. {/* min-version: 2.1.200 */}The same mapping applies when you pass the Anthropic model ID directly through --model or ANTHROPIC_MODEL. Versions without an override fall back to the built-in Amazon Bedrock model ID or any matching inference profile discovered at startup. Before v2.1.200, --model and ANTHROPIC_MODEL values reached Amazon Bedrock as-is without going through the override map. See Override model IDs per version for details on how overrides interact with availableModels and other model settings.
Startup model checks
When Claude Code starts with Amazon Bedrock configured, it verifies that the models it intends to use are accessible in your account.
If you have pinned a model version that is older than the current Claude Code default, and your account can invoke the newer version, Claude Code prompts you to update the pin. Accepting writes the new model ID to your user settings file and restarts Claude Code. Declining is remembered until the next default version change. Pins that point to an application inference profile ARN are skipped, since those are managed by your administrator.
If you have not pinned a model and the current default is unavailable in your account, Claude Code falls back for the current session and shows a notice. It tries earlier versions of the default model first and, when the default is an Opus model and no Opus version is available, falls back to the default Sonnet model. The fallback is not persisted. Enable the newer model in your Amazon Bedrock account or pin a version to make the choice permanent.
{/* min-version: 2.1.211 */}When you start the session on a specific Sonnet or Opus version, with --model, ANTHROPIC_MODEL, or the model setting, that version acts as the session's pinned default for the matching sonnet or opus alias. Claude Code skips the availability check for the built-in default your model replaces and starts on the model you configured, with no fallback notice.
Model aliases such as opus don't act as pins, and neither does a model ID Claude Code doesn't recognize, such as an application inference profile ARN.
IAM configuration
Create an IAM policy with the required permissions for Claude Code:
For more restrictive permissions, you can limit the Resource to specific inference profile ARNs.
bedrock:GetInferenceProfile lets Claude Code resolve an application inference profile ARN to its backing foundation model, which is used to select the correct request shape for that model.
If the token is missing this permission, Claude Code recovers automatically by retrying once with the alternate shape, so requests still succeed but each new model adds an extra round-trip. Granting the permission avoids the retry. This applies most often to AWS_BEARER_TOKEN_BEDROCK deployments, where the token's policy is typically narrower than a full IAM role.
Claude Sonnet 5, Opus 4.6 and later, and Sonnet 4.6 support the 1M token context window on Amazon Bedrock. Sonnet 5 is served through the Mantle endpoint and always runs with the 1M window, with no [1m] variant to select. For the other models, Claude Code automatically enables the extended context window when you select a 1M model variant.
Amazon Bedrock service tiers let you trade off cost against latency. Set ANTHROPIC_BEDROCK_SERVICE_TIER to default, flex, or priority:
export ANTHROPIC_BEDROCK_SERVICE_TIER=priority
Claude Code sends this as the X-Amzn-Bedrock-Service-Tier header on each request. Tier availability varies by model and region. Reserved capacity uses a provisioned throughput ARN as the model ID instead of this setting.
AWS Guardrails
Amazon Bedrock Guardrails let you implement content filtering for Claude Code. Create a Guardrail in the Amazon Bedrock console, publish a version, then add the Guardrail headers to your settings file. Enable Cross-Region inference on your Guardrail if you're using cross-region inference profiles.
Mantle is an Amazon Bedrock endpoint that serves Claude models through the native Anthropic API shape rather than the Amazon Bedrock Invoke API. It uses the same AWS credentials, IAM permissions, and awsAuthRefresh configuration described earlier on this page.
Enable Mantle
With AWS credentials already configured, set CLAUDE_CODE_USE_MANTLE to route requests to the Mantle endpoint:
Claude Code constructs the endpoint URL from the AWS region. {/* min-version: 2.1.172 */}As of v2.1.172, the region is resolved with the same precedence as Amazon Bedrock above; earlier versions use AWS_REGION only. To override the URL for a custom endpoint or gateway, set ANTHROPIC_BEDROCK_MANTLE_BASE_URL.
Run /status inside Claude Code to confirm. The provider line shows Amazon Bedrock (Mantle) when Mantle is active.
Select a Mantle model
Mantle uses model IDs prefixed with anthropic. and without a version suffix, for example anthropic.claude-sonnet-5 or anthropic.claude-haiku-4-5. The models available to your account depend on what your organization has been granted; additional model IDs are listed in your onboarding materials from AWS. Contact your AWS account team to request access to allowlisted models.
Set the model with the --model flag or with /model inside Claude Code:
claude --model anthropic.claude-haiku-4-5
Run Mantle alongside the Invoke API
The models available to you on Mantle may not include every model you use today. Setting both CLAUDE_CODE_USE_BEDROCK and CLAUDE_CODE_USE_MANTLE lets Claude Code call both endpoints from the same session. Model IDs that match the Mantle format are routed to Mantle, and all other model IDs go to the Amazon Bedrock Invoke API.
To surface a Mantle model in the /model picker, list its ID in availableModels in your settings file. This setting also restricts the picker to the listed entries. Listing anthropic.claude-haiku-4-5 removes the bare haiku alias from the picker, so also list version prefixes or full IDs for the versions you want to keep selectable. The Mantle ID and the haiku alias resolve to the same model family, so the merge keeps only the more specific entry. See Merge behavior:
Entries with the anthropic. prefix are added as custom picker options and routed to Mantle. Replace anthropic.claude-haiku-4-5 with the model ID your account has been granted. See Restrict model selection for how availableModels interacts with other model settings.
When both providers are active, /status shows Amazon Bedrock + Amazon Bedrock (Mantle).
Route Mantle through a gateway
If your organization routes model traffic through a centralized LLM gateway that injects AWS credentials server-side, disable client-side authentication so Claude Code sends requests without SigV4 signatures or x-api-key headers:
These variables are specific to the Mantle endpoint. See Environment variables for the full list.
Variable
Purpose
CLAUDE_CODE_USE_MANTLE
Enable the Mantle endpoint. Set to 1 or true.
ANTHROPIC_BEDROCK_MANTLE_BASE_URL
Override the default Mantle endpoint URL
CLAUDE_CODE_SKIP_MANTLE_AUTH
Skip client-side authentication for proxy setups
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION
Override AWS region for the Haiku-class model (shared with Amazon Bedrock)
Troubleshooting
Authentication loop with SSO and corporate proxies
If browser tabs spawn repeatedly when using AWS SSO, remove the awsAuthRefresh setting from your settings file. This can occur when corporate VPNs or TLS inspection proxies interrupt the SSO browser flow. Claude Code treats the interrupted connection as an authentication failure, re-runs awsAuthRefresh, and loops indefinitely.
If your network environment interferes with automatic browser-based SSO flows, use aws sso login manually before starting Claude Code instead of relying on awsAuthRefresh.
Region issues
If you encounter region issues:
Check model availability: aws bedrock list-inference-profiles --region your-region
Switch to a supported region: export AWS_REGION=us-east-1
Consider using inference profiles for cross-region access
If you receive an error "on-demand throughput isn't supported":
Claude Code uses the Amazon Bedrock Invoke API and does not support the Converse API.
Streaming errors behind a gateway or proxy
If streaming requests fail with an error that begins Bedrock streaming response has content-type, a gateway or proxy between Claude Code and Amazon Bedrock is transforming the streaming response. Amazon Bedrock streams responses in a binary event-stream format with the content-type application/vnd.amazon.eventstream, and Claude Code rejects a successful streaming response that reports a different content-type instead of decoding a body it can't read. The error names the content-type it received, commonly text/event-stream from an Amazon API Gateway and Lambda integration that re-emits the stream as server-sent events.
Before v2.1.208, the same misconfiguration surfaced as API Error: Truncated event message received after the whole response had been buffered.
To fix it, configure the gateway to pass the InvokeModelWithResponseStream response body and its Content-Type header through unmodified. If the gateway rewrites only the header and passes the binary body through intact, set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to skip the check until the gateway is fixed. With the check off, a response body that was transformed fails with Truncated event message received again.
Zero token counts in /context
The /context command counts tokens for each tool group by sending the tool schemas to the Amazon Bedrock count-tokens API. {/* min-version: 2.1.196 */}On Claude Code versions before v2.1.196, Amazon Bedrock rejected that request because the schemas carried fields its count-tokens API doesn't accept, so every tool group showed 0 tokens. Other rows in the breakdown, such as messages and memory files, aren't affected.
Update to v2.1.196 or later.
Mantle endpoint errors
If /status does not show Amazon Bedrock (Mantle) after you set CLAUDE_CODE_USE_MANTLE, the variable is not reaching the process. Confirm it is exported in the shell where you launched claude, or set it in the env block of your settings file.
A 403 from the Mantle endpoint with valid credentials means your AWS account has not been granted access to the model you requested. Contact your AWS account team to request access.
A 400 that names the model ID means that model is not served on Mantle. Mantle has its own model lineup separate from the standard Amazon Bedrock catalog, so inference profile IDs such as us.anthropic.claude-sonnet-4-6 will not work. Use a Mantle-format ID, or enable both endpoints so Claude Code routes each request to the endpoint where the model is available.
105 <Step title="Follow the wizard prompts">105 <Step title="Follow the wizard prompts">
106 Choose how you authenticate to AWS: an AWS profile detected from your `~/.aws` directory, an Amazon Bedrock API key, an access key and secret, or credentials already in your environment. The wizard picks up your region, verifies which Claude models your account can invoke, and lets you pin them. It saves the result to the `env` block of your [user settings file](/en/settings), so you don't need to export environment variables yourself.106 Choose how you authenticate to AWS: an AWS profile detected from your `~/.aws` directory, an Amazon Bedrock API key, an access key and secret, or credentials already in your environment. The wizard picks up your region, verifies which Claude models your account can invoke, and lets you pin them. It saves the result to the `env` block of your [user settings file](/docs/en/settings), so you don't need to export environment variables yourself.
107 </Step>107 </Step>
108</Steps>108</Steps>
109109
110After you've signed in, run `/setup-bedrock` any time to reopen the wizard and change your credentials, region, or model pins. The model pin step starts from your currently pinned models. The wizard writes to `~/.claude/settings.json`, or to `$CLAUDE_CONFIG_DIR/settings.json` when [`CLAUDE_CONFIG_DIR`](/en/env-vars#variables) is set.110After you've signed in, run `/setup-bedrock` any time to reopen the wizard and change your credentials, region, or model pins. The model pin step starts from your currently pinned models. The wizard writes to `~/.claude/settings.json`, or to `$CLAUDE_CONFIG_DIR/settings.json` when [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars#variables) is set.
111111
112## Set up manually112## Set up manually
113113
176176
177Before v2.1.207, Claude Code resolved the chain on every API request, so an SSO-backed profile requested fresh credentials from IAM Identity Center each time and could be throttled in large deployments.177Before v2.1.207, Claude Code resolved the chain on every API request, so an SSO-backed profile requested fresh credentials from IAM Identity Center each time and could be throttled in large deployments.
178178
179The cache covers every credential option above except an Amazon Bedrock API key, which doesn't use the provider chain. To resolve the chain on every request instead, set [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/en/env-vars).179The cache covers every credential option above except an Amazon Bedrock API key, which doesn't use the provider chain. To resolve the chain on every request instead, set [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/en/env-vars).
180180
181Each resolve of the chain times out after 60 seconds. If a step in the chain stalls, for example a `credential_process` helper that waits for input it can't receive, the request fails with [`AWS default-chain credential resolve timed out`](/en/errors#aws-default-chain-credential-resolve-timed-out). If your chain runs an interactive sign-in that legitimately needs longer, such as browser-based SSO with MFA through a wrapper like `aws-vault`, raise the limit in milliseconds with [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/en/env-vars). Before v2.1.207, a stalled credential resolution left the request waiting indefinitely.181Each resolve of the chain times out after 60 seconds. If a step in the chain stalls, for example a `credential_process` helper that waits for input it can't receive, the request fails with [`AWS default-chain credential resolve timed out`](/docs/en/errors#aws-default-chain-credential-resolve-timed-out). If your chain runs an interactive sign-in that legitimately needs longer, such as browser-based SSO with MFA through a wrapper like `aws-vault`, raise the limit in milliseconds with [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/en/env-vars). Before v2.1.207, a stalled credential resolution left the request waiting indefinitely.
185Claude Code supports automatic credential refresh for AWS SSO and corporate identity providers. Add these settings to your Claude Code settings file (see [Settings](/en/settings) for file locations).185Claude Code supports automatic credential refresh for AWS SSO and corporate identity providers. Add these settings to your Claude Code settings file (see [Settings](/docs/en/settings) for file locations).
186186
187These two settings have different trigger conditions:187These two settings have different trigger conditions:
188188
252252
253 The active profile is `AWS_PROFILE` if set, otherwise `default`. Set `AWS_SHARED_CREDENTIALS_FILE` or `AWS_CONFIG_FILE` to point at non-default file paths. Run `/status` to see the resolved region. When the region came from your AWS config files or the default fallback, `/status` also notes the source. On v2.1.171 and earlier, Claude Code does not read the AWS config files, so set `AWS_REGION` explicitly.253 The active profile is `AWS_PROFILE` if set, otherwise `default`. Set `AWS_SHARED_CREDENTIALS_FILE` or `AWS_CONFIG_FILE` to point at non-default file paths. Run `/status` to see the resolved region. When the region came from your AWS config files or the default fallback, `/status` also notes the source. On v2.1.171 and earlier, Claude Code does not read the AWS config files, so set `AWS_REGION` explicitly.
254* When using Amazon Bedrock, the `/logout` command is unavailable since authentication is handled through AWS credentials.254* When using Amazon Bedrock, the `/logout` command is unavailable since authentication is handled through AWS credentials.
255* The WebSearch tool is not available on Amazon Bedrock. See [WebSearch tool behavior](/en/tools-reference#websearch-tool-behavior).255* The WebSearch tool is not available on Amazon Bedrock. See [WebSearch tool behavior](/docs/en/tools-reference#websearch-tool-behavior).
256* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/settings) for more information.256* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/docs/en/settings) for more information.
257257
258### 4. Pin model versions258### 4. Pin model versions
259259
263263
264Set these environment variables to specific Amazon Bedrock model IDs.264Set these environment variables to specific Amazon Bedrock model IDs.
265265
266Without `ANTHROPIC_DEFAULT_OPUS_MODEL`, the `opus` alias on Amazon Bedrock resolves to Opus 4.8, and without `ANTHROPIC_DEFAULT_SONNET_MODEL`, the `sonnet` alias resolves to Sonnet 4.5. This example pins each alias to a specific version:266Without `ANTHROPIC_DEFAULT_OPUS_MODEL`, the `opus` alias on Amazon Bedrock resolves to Opus 5, and without `ANTHROPIC_DEFAULT_SONNET_MODEL`, the `sonnet` alias resolves to Sonnet 4.5. This example pins each alias to a specific version:
274These variables use cross-region inference profile IDs (with the `us.` prefix). If you use a different region prefix or application inference profiles, adjust accordingly. In AWS GovCloud regions, use the `us-gov.` prefix. For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.274These variables use cross-region inference profile IDs (with the `us.` prefix). If you use a different region prefix or application inference profiles, adjust accordingly. In AWS GovCloud regions, use the `us-gov.` prefix. For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/docs/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.
275275
276Claude Code uses these default models when no pinning variables are set:276Claude Code uses these default models when no pinning variables are set:
277277
278| Model type | Default value |278| Model type | Default value |
280| Primary model | `us.anthropic.claude-opus-4-8`|280| Primary model | `us.anthropic.claude-opus-5`|
281| Small/fast model | `us.anthropic.claude-sonnet-4-5-20250929-v1:0` |281| Small/fast model | `us.anthropic.claude-sonnet-4-5-20250929-v1:0` |
282282
283Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Amazon Bedrock, Claude Code uses the default Sonnet model for background tasks because Haiku may not be enabled in every account or region. Two selections change which model carries them:283Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Amazon Bedrock, Claude Code uses the default Sonnet model for background tasks because Haiku may not be enabled in every account or region. Two selections change which model carries them:
289 Opus models have a higher per-token price than Sonnet models, so a deployment that doesn't pin a primary model is billed at the Opus rate once it updates to v2.1.207 or later. To keep Sonnet 4.5 as the primary model, set `ANTHROPIC_MODEL` to its full model ID. A deployment that steers the default with `ANTHROPIC_DEFAULT_SONNET_MODEL` and doesn't set `ANTHROPIC_DEFAULT_OPUS_MODEL` keeps its steered Sonnet model as the default.289 Opus models have a higher per-token price than Sonnet models, so a deployment that doesn't pin a primary model is billed at the Opus rate once it updates to v2.1.207 or later. To keep Sonnet 4.5 as the primary model, set `ANTHROPIC_MODEL` to its full model ID. A deployment that steers the default with `ANTHROPIC_DEFAULT_SONNET_MODEL` and doesn't set `ANTHROPIC_DEFAULT_OPUS_MODEL` keeps its steered Sonnet model as the default.
290</Warning>290</Warning>
291291
292{/* min-version: 2.1.207 */}Before v2.1.207, the primary model on Amazon Bedrock defaulted to Sonnet 4.5, the `opus` alias resolved to Opus 4.6, and background tasks always used the primary model.292{/* min-version: 2.1.219 */}On v2.1.207 through v2.1.218, the primary model on Amazon Bedrock defaulted to Opus 4.8 and the `opus` alias resolved to Opus 4.8. {/* min-version: 2.1.207 */}Before v2.1.207, the primary model defaulted to Sonnet 4.5, the `opus` alias resolved to Opus 4.6, and background tasks always used the primary model.
293293
294To customize models further, use one of these methods:294To customize models further, use one of these methods:
311The 1-hour cache TTL is billed at a higher rate than the 5-minute default. See [cache lifetime](/en/prompt-caching#cache-lifetime).311The 1-hour cache TTL is billed at a higher rate than the 5-minute default. See [cache lifetime](/docs/en/prompt-caching#cache-lifetime).
312312
313<Note>Prompt caching may not be available in all Amazon Bedrock regions. If cache token counts stay at zero, check [supported models, regions, and limits](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models) in the Amazon Bedrock documentation.</Note>313<Note>Prompt caching may not be available in all Amazon Bedrock regions. If cache token counts stay at zero, check [supported models, regions, and limits](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models) in the Amazon Bedrock documentation.</Note>
314314
315#### Map each model version to an inference profile315#### Map each model version to an inference profile
316316
317The `ANTHROPIC_DEFAULT_*_MODEL` environment variables configure one inference profile per model family. If your organization needs to expose several versions of the same family in the `/model` picker, each routed to its own application inference profile ARN, use the `modelOverrides` setting in your [settings file](/en/settings#settings-files) instead.317The `ANTHROPIC_DEFAULT_*_MODEL` environment variables configure one inference profile per model family. If your organization needs to expose several versions of the same family in the `/model` picker, each routed to its own application inference profile ARN, use the `modelOverrides` setting in your [settings file](/docs/en/settings#settings-files) instead.
318318
319This example maps four Opus versions to distinct ARNs so users can switch between them without bypassing your organization's inference profiles:319This example maps four Opus versions to distinct ARNs so users can switch between them without bypassing your organization's inference profiles:
320320
329}329}
330```330```
331331
332When a user selects one of these versions in `/model`, Claude Code calls Amazon Bedrock with the mapped ARN. {/* min-version: 2.1.200 */}The same mapping applies when you pass the Anthropic model ID directly through `--model` or `ANTHROPIC_MODEL`. Versions without an override fall back to the built-in Amazon Bedrock model ID or any matching inference profile discovered at startup. Before v2.1.200, `--model` and `ANTHROPIC_MODEL` values reached Amazon Bedrock as-is without going through the override map. See [Override model IDs per version](/en/model-config#override-model-ids-per-version) for details on how overrides interact with `availableModels` and other model settings.332When a user selects one of these versions in `/model`, Claude Code calls Amazon Bedrock with the mapped ARN. {/* min-version: 2.1.200 */}The same mapping applies when you pass the Anthropic model ID directly through `--model` or `ANTHROPIC_MODEL`. Versions without an override fall back to the built-in Amazon Bedrock model ID or any matching inference profile discovered at startup. Before v2.1.200, `--model` and `ANTHROPIC_MODEL` values reached Amazon Bedrock as-is without going through the override map. See [Override model IDs per version](/docs/en/model-config#override-model-ids-per-version) for details on how overrides interact with `availableModels` and other model settings.
333333
334## Startup model checks334## Startup model checks
335335
336When Claude Code starts with Amazon Bedrock configured, it verifies that the models it intends to use are accessible in your account.336When Claude Code starts with Amazon Bedrock configured, it verifies that the models it intends to use are accessible in your account.
337337
338If you have pinned a model version that is older than the current Claude Code default, and your account can invoke the newer version, Claude Code prompts you to update the pin. Accepting writes the new model ID to your [user settings file](/en/settings) and restarts Claude Code. Declining is remembered until the next default version change. Pins that point to an [application inference profile ARN](#map-each-model-version-to-an-inference-profile) are skipped, since those are managed by your administrator.338If you have pinned a model version that is older than the current Claude Code default, and your account can invoke the newer version, Claude Code prompts you to update the pin. Accepting writes the new model ID to your [user settings file](/docs/en/settings) and restarts Claude Code. Declining is remembered until the next default version change. Pins that point to an [application inference profile ARN](#map-each-model-version-to-an-inference-profile) are skipped, since those are managed by your administrator.
339339
340If you have not pinned a model and the current default is unavailable in your account, Claude Code falls back for the current session and shows a notice. It tries earlier versions of the default model first and, when the default is an Opus model and no Opus version is available, falls back to the default Sonnet model. The fallback is not persisted. Enable the newer model in your Amazon Bedrock account or [pin a version](#4-pin-model-versions) to make the choice permanent.340If you have not pinned a model and the current default is unavailable in your account, Claude Code falls back for the current session and shows a notice. It tries earlier versions of the default model first and, when the default is an Opus model and no Opus version is available, falls back to the default Sonnet model. The fallback is not persisted. Enable the newer model in your Amazon Bedrock account or [pin a version](#4-pin-model-versions) to make the choice permanent.
341341
342{/* min-version: 2.1.211 */}When you start the session on a specific Sonnet or Opus version, with `--model`, `ANTHROPIC_MODEL`, or the [`model` setting](/en/settings), that version acts as the session's pinned default for the matching `sonnet` or `opus` alias. Claude Code skips the availability check for the built-in default your model replaces and starts on the model you configured, with no fallback notice.342{/* min-version: 2.1.211 */}When you start the session on a specific Sonnet or Opus version, with `--model`, `ANTHROPIC_MODEL`, or the [`model` setting](/docs/en/settings), that version acts as the session's pinned default for the matching `sonnet` or `opus` alias. Claude Code skips the availability check for the built-in default your model replaces and starts on the model you configured, with no fallback notice.
343343
344Model aliases such as `opus` don't act as pins, and neither does a model ID Claude Code doesn't recognize, such as an application inference profile ARN.344Model aliases such as `opus` don't act as pins, and neither does a model ID Claude Code doesn't recognize, such as an application inference profile ARN.
345345
402402
403Claude Sonnet 5, Opus 4.6 and later, and Sonnet 4.6 support the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) on Amazon Bedrock. Sonnet 5 is served through the [Mantle endpoint](#use-the-mantle-endpoint) and always runs with the 1M window, with no `[1m]` variant to select. For the other models, Claude Code automatically enables the extended context window when you select a 1M model variant.403Claude Sonnet 5, Opus 4.6 and later, and Sonnet 4.6 support the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) on Amazon Bedrock. Sonnet 5 is served through the [Mantle endpoint](#use-the-mantle-endpoint) and always runs with the 1M window, with no `[1m]` variant to select. For the other models, Claude Code automatically enables the extended context window when you select a 1M model variant.
404404
405The [setup wizard](#sign-in-with-bedrock) offers a 1M context option when it pins models. To enable it for a manually pinned model instead, append `[1m]` to the model ID. See [Pin models for third-party deployments](/en/model-config#pin-models-for-third-party-deployments) for details.405The [setup wizard](#sign-in-with-bedrock) offers a 1M context option when it pins models. To enable it for a manually pinned model instead, append `[1m]` to the model ID. See [Pin models for third-party deployments](/docs/en/model-config#pin-models-for-third-party-deployments) for details.
406406
407## Service tiers407## Service tiers
408408
416416
417## AWS Guardrails417## AWS Guardrails
418418
419[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) let you implement content filtering for Claude Code. Create a Guardrail in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), publish a version, then add the Guardrail headers to your [settings file](/en/settings). Enable Cross-Region inference on your Guardrail if you're using cross-region inference profiles.419[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) let you implement content filtering for Claude Code. Create a Guardrail in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), publish a version, then add the Guardrail headers to your [settings file](/docs/en/settings). Enable Cross-Region inference on your Guardrail if you're using cross-region inference profiles.
467To surface a Mantle model in the `/model` picker, list its ID in `availableModels` in your [settings file](/en/settings). This setting also restricts the picker to the listed entries. Listing `anthropic.claude-haiku-4-5` removes the bare `haiku` alias from the picker, so also list version prefixes or full IDs for the versions you want to keep selectable. The Mantle ID and the `haiku` alias resolve to the same model family, so the merge keeps only the more specific entry. See [Merge behavior](/en/model-config#merge-behavior):467To surface a Mantle model in the `/model` picker, list its ID in `availableModels` in your [settings file](/docs/en/settings). This setting also restricts the picker to the listed entries. Listing `anthropic.claude-haiku-4-5` removes the bare `haiku` alias from the picker, so also list version prefixes or full IDs for the versions you want to keep selectable. The Mantle ID and the `haiku` alias resolve to the same model family, so the merge keeps only the more specific entry. See [Merge behavior](/docs/en/model-config#merge-behavior):
468468
469```json theme={null}469```json theme={null}
470{470{
472}472}
473```473```
474474
475Entries with the `anthropic.` prefix are added as custom picker options and routed to Mantle. Replace `anthropic.claude-haiku-4-5` with the model ID your account has been granted. See [Restrict model selection](/en/model-config#restrict-model-selection) for how `availableModels` interacts with other model settings.475Entries with the `anthropic.` prefix are added as custom picker options and routed to Mantle. Replace `anthropic.claude-haiku-4-5` with the model ID your account has been granted. See [Restrict model selection](/docs/en/model-config#restrict-model-selection) for how `availableModels` interacts with other model settings.
476476
477When both providers are active, `/status` shows `Amazon Bedrock + Amazon Bedrock (Mantle)`.477When both providers are active, `/status` shows `Amazon Bedrock + Amazon Bedrock (Mantle)`.
478478
479### Route Mantle through a gateway479### Route Mantle through a gateway
480480
481If your organization routes model traffic through a centralized [LLM gateway](/en/llm-gateway) that injects AWS credentials server-side, disable client-side authentication so Claude Code sends requests without SigV4 signatures or `x-api-key` headers:481If your organization routes model traffic through a centralized [LLM gateway](/docs/en/llm-gateway) that injects AWS credentials server-side, disable client-side authentication so Claude Code sends requests without SigV4 signatures or `x-api-key` headers:
491These variables are specific to the Mantle endpoint. See [Environment variables](/en/env-vars) for the full list.491These variables are specific to the Mantle endpoint. See [Environment variables](/docs/en/env-vars) for the full list.
502### Authentication loop with SSO and corporate proxies502### Authentication loop with SSO and corporate proxies
503503
504If browser tabs spawn repeatedly when using AWS SSO, remove the `awsAuthRefresh` setting from your [settings file](/en/settings). This can occur when corporate VPNs or TLS inspection proxies interrupt the SSO browser flow. Claude Code treats the interrupted connection as an authentication failure, re-runs `awsAuthRefresh`, and loops indefinitely.504If browser tabs spawn repeatedly when using AWS SSO, remove the `awsAuthRefresh` setting from your [settings file](/docs/en/settings). This can occur when corporate VPNs or TLS inspection proxies interrupt the SSO browser flow. Claude Code treats the interrupted connection as an authentication failure, re-runs `awsAuthRefresh`, and loops indefinitely.
505505
506If your network environment interferes with automatic browser-based SSO flows, use `aws sso login` manually before starting Claude Code instead of relying on `awsAuthRefresh`.506If your network environment interferes with automatic browser-based SSO flows, use `aws sso login` manually before starting Claude Code instead of relying on `awsAuthRefresh`.
507507
525525
526Before v2.1.208, the same misconfiguration surfaced as `API Error: Truncated event message received` after the whole response had been buffered.526Before v2.1.208, the same misconfiguration surfaced as `API Error: Truncated event message received` after the whole response had been buffered.
527527
528To fix it, configure the gateway to pass the `InvokeModelWithResponseStream` response body and its `Content-Type` header through unmodified. If the gateway rewrites only the header and passes the binary body through intact, set [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/en/env-vars) to skip the check until the gateway is fixed. With the check off, a response body that was transformed fails with `Truncated event message received` again.528To fix it, configure the gateway to pass the `InvokeModelWithResponseStream` response body and its `Content-Type` header through unmodified. If the gateway rewrites only the header and passes the binary body through intact, set [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/docs/en/env-vars) to skip the check until the gateway is fixed. With the check off, a response body that was transformed fails with `Truncated event message received` again.
529529
530### Zero token counts in /context530### Zero token counts in /context
538If `/status` does not show `Amazon Bedrock (Mantle)` after you set `CLAUDE_CODE_USE_MANTLE`, the variable is not reaching the process. Confirm it is exported in the shell where you launched `claude`, or set it in the `env` block of your [settings file](/en/settings).538If `/status` does not show `Amazon Bedrock (Mantle)` after you set `CLAUDE_CODE_USE_MANTLE`, the variable is not reaching the process. Confirm it is exported in the shell where you launched `claude`, or set it in the `env` block of your [settings file](/docs/en/settings).
539539
540A `403` from the Mantle endpoint with valid credentials means your AWS account has not been granted access to the model you requested. Contact your AWS account team to request access.540A `403` from the Mantle endpoint with valid credentials means your AWS account has not been granted access to the model you requested. Contact your AWS account team to request access.
