Claude Code on Amazon Bedrock

Learn about configuring Claude Code through Amazon Bedrock, including setup, IAM configuration, and troubleshooting.

Prerequisites

Before configuring Claude Code with Bedrock, ensure you have:

An AWS account with Bedrock access enabled
Access to desired Claude models (for example, Claude Sonnet 4.5) in Bedrock
AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)
Appropriate IAM permissions

Setup

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

Ensure you have the right IAM permissions (see more on that below)
Navigate to the Amazon Bedrock console
Select Chat/Text playground
Choose any Anthropic model and you will be prompted to fill out the use case form

2. Configure AWS credentials

Claude Code uses the default AWS SDK credential chain. Set up your credentials using one of these methods:

Option A: AWS CLI configuration

aws configure

Option B: Environment variables (access key)

export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token

Option C: Environment variables (SSO profile)

aws sso login --profile=<your-profile-name>

export AWS_PROFILE=your-profile-name

Option D: Bedrock API keys

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Bedrock API keys provide a simpler authentication method without needing full AWS credentials. Learn more about Bedrock API keys.

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

When Claude Code detects that your AWS credentials are expired (either locally based on their timestamp or when Bedrock returns a credential error), it will automatically run your configured awsAuthRefresh and/or awsCredentialExport commands to obtain new credentials before retrying the request.

Example configuration

{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}

Configuration settings explained

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. Output is captured silently and not shown to the user. The command must output JSON in this format:

{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value"
  }
}

3. Configure Claude Code

Set the following environment variables to enable Bedrock:

# Enable Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # or your preferred region

# Optional: Override the region for the small/fast model (Haiku)
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

For VS Code Extension users: Configure environment variables in the VS Code extension settings instead of exporting them in your shell. See Using Third-Party Providers in VS Code for detailed instructions. All environment variables shown in this guide should work when configured through the VS Code extension settings.

When enabling Bedrock for Claude Code, keep the following in mind:

AWS_REGION is a required environment variable. Claude Code does not read from the .aws config file for this setting.
When using Bedrock, the /login and /logout commands are disabled 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. Model configuration

Claude Code uses these default models for Bedrock:

Model type	Default value
Primary model	`global.anthropic.claude-sonnet-4-5-20250929-v1:0`
Small/fast model	`us.anthropic.claude-haiku-4-5-20251001-v1:0`

To customize models, use one of these methods:

# Using inference profile ID
export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-5-20250929-v1:0'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

# Using application inference profile ARN
export 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

5. Output token configuration

These are the recommended token settings for Claude Code with Amazon Bedrock:

# Recommended output token settings for Bedrock
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096
export MAX_THINKING_TOKENS=1024

Why these values:

CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096: Bedrock's burndown throttling logic sets a minimum of 4096 tokens as the max_token penalty. Setting this lower won't reduce costs but may cut off long tool uses, causing the Claude Code agent loop to fail persistently. Claude Code typically uses less than 4096 output tokens without extended thinking, but may need this headroom for tasks involving significant file creation or Write tool usage.
MAX_THINKING_TOKENS=1024: This provides space for extended thinking without cutting off tool use responses, while still maintaining focused reasoning chains. This balance helps prevent trajectory changes that aren't always helpful for coding tasks specifically.

IAM configuration

Create an IAM policy with the required permissions for Claude Code:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowModelAndInferenceProfileAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles"
      ],
      "Resource": [
        "arn:aws:bedrock:*:*:inference-profile/*",
        "arn:aws:bedrock:*:*:application-inference-profile/*",
        "arn:aws:bedrock:*:*:foundation-model/*"
      ]
    },
    {
      "Sid": "AllowMarketplaceSubscription",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:ViewSubscriptions",
        "aws-marketplace:Subscribe"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:CalledViaLast": "bedrock.amazonaws.com"
        }
      }
    }
  ]
}

For more restrictive permissions, you can limit the Resource to specific inference profile ARNs.

For details, see Bedrock IAM documentation.

Troubleshooting

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":

Specify the model as an inference profile ID

Claude Code uses the Bedrock Invoke API and does not support the Converse API.

Additional resources

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

amazon-bedrock.md +7 −9

7Before configuring Claude Code with Bedrock, ensure you have:7Before configuring Claude Code with Bedrock, ensure you have:

8 8

9* An AWS account with Bedrock access enabled9* An AWS account with Bedrock access enabled

~~10* Access to desired Claude models (e.g., Claude Sonnet 4.5) in Bedrock~~10* Access to desired Claude models (for example, Claude Sonnet 4.5) in Bedrock

11* AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)11* AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)

12* Appropriate IAM permissions12* Appropriate IAM permissions

13 13

75 75

76##### Configuration settings explained76##### Configuration settings explained

77 77

78**`awsAuthRefresh`**: Use this for commands that modify the `.aws` directory (e.g., updating credentials, SSO cache, or config files). Output is shown to the user (but user input is not supported), making it suitable for browser-based authentication flows where the CLI displays a code to enter in the browser.78**`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.

79 79

80**`awsCredentialExport`**: Only use this if you cannot modify `.aws` and must directly return credentials. Output is captured silently (not shown to the user). The command must output JSON in this format:80**`awsCredentialExport`**: Only use this if you can't modify `.aws` and must directly return credentials. Output is captured silently and not shown to the user. The command must output JSON in this format:

81 81

82```json theme={null}82```json theme={null}

83{83{

121 121

122<Note>122<Note>

123 For Bedrock users, Claude Code will not automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (e.g., `us.anthropic.claude-haiku-4-5-20251001-v1:0`).123 For Bedrock users, Claude Code won't automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (for example, `us.anthropic.claude-haiku-4-5-20251001-v1:0`).

124</Note>124</Note>

125 125

126To customize models, use one of these methods:126To customize models, use one of these methods:

137export DISABLE_PROMPT_CACHING=1137export DISABLE_PROMPT_CACHING=1

138```138```

139 139

140<Note>140<Note>[Prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) may not be available in all regions.</Note>

141 [Prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) may not be available in all regions

142</Note>

143 141

144### 5. Output token configuration142### 5. Output token configuration

145 143

146When using Claude Code with Amazon Bedrock, we recommend the following token settings:144These are the recommended token settings for Claude Code with Amazon Bedrock:

147 145

148```bash theme={null}146```bash theme={null}

149# Recommended output token settings for Bedrock147# Recommended output token settings for Bedrock

153 151

154**Why these values:**152**Why these values:**

155 153

156* **`CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096`**: Bedrock's burndown throttling logic sets a minimum of 4096 tokens as the max\_token penalty. Setting this lower won't reduce costs but may cut off long tool uses, causing the Claude Code agent loop to fail persistently. Claude Code typically uses less than 4096 output tokens without extended thinking, but may need this headroom for tasks involving significant file creation or Write tool usage.154* **`CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096`**: Bedrock's burndown throttling logic sets a minimum of 4096 tokens as the `max_token` penalty. Setting this lower won't reduce costs but may cut off long tool uses, causing the Claude Code agent loop to fail persistently. Claude Code typically uses less than 4096 output tokens without extended thinking, but may need this headroom for tasks involving significant file creation or Write tool usage.

157 155

158* **`MAX_THINKING_TOKENS=1024`**: This provides space for extended thinking without cutting off tool use responses, while still maintaining focused reasoning chains. This balance helps prevent trajectory changes that aren't always helpful for coding tasks specifically.156* **`MAX_THINKING_TOKENS=1024`**: This provides space for extended thinking without cutting off tool use responses, while still maintaining focused reasoning chains. This balance helps prevent trajectory changes that aren't always helpful for coding tasks specifically.

159 157