Complete Guide to Running Claude Code on Amazon Bedrock

Running Claude Code on Amazon Bedrock: A Complete Enterprise Deployment Guide

Claude Code has become a core tool in many developers' daily workflows — it reads codebases, creates and edits files, runs commands, and integrates with external tools via MCP and the command line. But for enterprise teams with data residency and billing compliance requirements, using Anthropic's official API directly is often not an option.

The good news is that you can run Claude Code entirely on Amazon Bedrock, keeping all inference within AWS infrastructure to meet security, compliance, and cost governance requirements.

This guide provides a comprehensive walkthrough of deploying Claude Code on Bedrock, covering environment configuration, cross-region inference, prompt caching, cost attribution, guardrails, and the new Mantle endpoint.

Why Run Claude Code on Amazon Bedrock

About Amazon Bedrock: Amazon Bedrock is AWS's fully managed foundation model service, officially launched in 2023. It allows enterprises to access large language models from Anthropic, Meta, Mistral, Cohere, and others through a unified API — without managing the underlying GPU infrastructure. Its core design philosophy is "model as a service" — inference runs inside AWS's VPC-isolated environment, and data does not flow across accounts. This makes it one of the primary paths for regulated industries like finance, healthcare, and government to adopt generative AI.

For enterprise teams, the most compelling reason is data never leaves AWS. AWS does not use your code or prompts to train models, nor does it share that information with model providers. When running through Bedrock, telemetry data that would otherwise be sent to Anthropic (including feedback data) is disabled by default — exactly what teams with strict data residency requirements need.

The second reason is familiar infrastructure and compliance tooling. You can reuse IAM credentials, Amazon CloudWatch, AWS CloudTrail logs, and Bedrock Guardrails content filtering. If your organization already runs on AWS, this solution integrates seamlessly into your existing stack.

The third reason is unified billing. Usage flows directly into your existing AWS bill, with no additional vendor contracts required. Later in this guide, we'll also cover how to break down costs by team and by user.

Environment Configuration: Two Core Variables to Get Started

Before you begin, you'll need Claude Code and the AWS CLI installed, an AWS account, and IAM permissions to invoke Bedrock models.

The key to configuration is routing Claude Code to Bedrock instead of the Anthropic API. You can run claude, then type /config to open settings, or edit the .claude/settings.json file directly. The two most essential variables are:

• CLAUDE_CODE_USE_BEDROCK=1: The switch that tells Claude Code to point to Bedrock
• AWS_REGION: Specifies which region requests are sent to

These two are the minimum requirements for running on Bedrock. You can also set a model variable to pin a specific version and precisely control which model is used. To look up valid model IDs, run aws bedrock list-foundation-models --by-provider to get a list of referenceable foundation models.

Credential Management and Auto-Refresh

The AWS SDK credential chain is a mechanism that automatically looks up credentials in priority order: it checks environment variables, the ~/.aws/credentials file, IAM Instance Profiles (EC2/ECS), IAM Identity Center (SSO), and other sources in sequence. This means developers don't need to hardcode Access Keys in code or config files — the SDK automatically selects the most appropriate credentials for the current environment, significantly reducing the risk of key exposure.

Claude Code follows this standard AWS SDK credential chain — if your AWS CLI already has credentials configured, it will use them automatically. If you're using IAM Identity Center (SSO), temporary credentials typically expire after one hour. But expiration won't interrupt your session: by adding an awsAuthRefresh configuration to your settings, Claude Code can automatically obtain new credentials in the background to keep sessions continuous.

Three Levels of Configuration Scope

Settings are divided into three scopes based on where they're stored:

• User-level: Located at ~/.claude/settings.json in your home directory, applies to all projects on the machine. Typically used for Bedrock environment variables and model preferences.
• Project-level: Located in the repository and committed to Git, applies to all collaborators.
• Local-level: Located at .claude/settings.local.json in the repository, applies only to you personally — ideal for individual overrides.

When the same setting exists at multiple scopes, the higher-priority scope takes precedence. For team collaboration, it's recommended to use project-level settings to lock in the model version and region and commit them to Git, while letting individual developers make personalized adjustments at the local level.

Cross-Region Inference: Solving Throttling Issues

Heavy users frequently encounter throttling — errors caused by capacity limits or hitting rate caps. Bedrock's cross-region inference effectively mitigates this issue by automatically routing requests to regions with available capacity, without requiring you to build your own client-side load balancing. Pricing stays the same; you simply get higher throughput.

Compliance considerations for cross-region inference: While cross-region inference improves throughput, it also introduces compliance complexity around data residency. With the EU Profile, for example, requests may be routed between Ireland (eu-west-1) and Frankfurt (eu-central-1) — both within the EU under GDPR jurisdiction, but enterprises should verify whether internal compliance policies permit cross-member-state data flows. The US Profile guarantees data stays within the United States, suitable for scenarios with explicit geographic constraints like FedRAMP and ITAR. The Global Profile offers the highest throughput, but data may flow through Asia-Pacific regions, making it unsuitable for use cases with strict geographic restrictions.

This is all controlled via the model ID in your settings file:

• Single-region ID (no prefix): Locked to a single region, throughput constrained by that region's limits. Suitable for latency-sensitive scenarios or cases requiring deterministic routing.
• Geographic cross-region profiles: Prefixed with US, EU, or APAC — requests can flow between regions within that geography. For example, the US prefix keeps traffic within the United States but can switch regions when one is congested. This is the recommended default for most teams.
• Global cross-region profile: Prefixed with global — requests can be routed to any supported region worldwide for maximum available throughput.

The Mantle Endpoint: AWS's Recommended Next-Generation Option

All of the configurations described above use the standard Bedrock runtime endpoint, but AWS now recommends a newer endpoint — Amazon Bedrock Mantle.

Mantle offers several advantages:

Native API compatibility: It serves requests through the model's native API format (such as the Anthropic Messages API), with better throughput handling, separate input/output token quotas, and performance tiers.

Zero operator access: This is a cloud security architecture commitment meaning that cloud provider engineers technically cannot access customer runtime data. It's typically implemented using hardware roots of trust (such as AWS Nitro System's confidential computing capabilities) and strict key management architecture — inference data is always encrypted with customer account-specific keys during transit and processing, so even AWS personnel with physical server access cannot decrypt the content. This is fundamentally different from traditional "trust but no access" promises: the former is a contractual constraint, the latter is a technical one. Even AWS, which operates Bedrock, cannot access your inference data — there are no backdoors, admin overrides, or technical paths for support engineers to retrieve your prompts in the system architecture. Your code conversations sent to Bedrock via Claude Code exist entirely within your own AWS account.

Superior scheduling architecture: Mantle uses an advanced work queue mechanism rather than hard per-account rate limiting. When capacity is tight, requests are briefly queued rather than immediately rejected — meaning fewer errors for heavy users.

Quota separation: Standard Bedrock uses a shared token pool for both input and output, and output tokens consume a disproportionately higher share. Mantle separates input and output into independent pools — for agentic workloads that need to feed large codebases and generate large amounts of code, generating code won't consume the quota for sending context, and vice versa.

Switching to Mantle only requires adding CLAUDE_CODE_USE_MANTLE=1 to your settings. Note that model IDs on Mantle have a different format, prefixed with anthropic and without a region prefix. After starting up, run /status — the provider line will show Amazon Bedrock Mantle.

Prompt Caching: A Cost Optimization Tool That's Enabled by Default

How prompt caching works: Prompt caching is one of the core optimization technologies for LLM inference. The principle involves persisting already-computed KV Cache (key-value cache) — when the prefix portion of a subsequent request matches the cache, the Prefill computation stage for those tokens is skipped. Since Prefill is the primary source of inference latency, cache hits can significantly reduce time-to-first-token (TTFT). For scenarios like Claude Code that repeatedly inject a full codebase context, the caching benefit is especially substantial — system prompts, file tree structures, and other parts of the session that remain unchanged only need to be computed once.

Prompt caching is enabled by default and requires no configuration. As you interact back and forth with Claude Code, shared context between messages is cached to avoid reprocessing every turn, delivering up to 90% cost reduction and 85% latency reduction.

Note that the default cache window is 5 minutes. You get the full benefit when sending prompts in rapid succession, but once you go check Slack, review a PR, or grab a coffee, 5 minutes passes quickly and the cache expires. You can add the corresponding configuration to your settings' environment variables block to extend the cache to 1 hour — at the cost of slightly higher write costs per cached token. But for active developers who frequently context-switch during sessions, this investment pays off. (The one-hour extension currently requires the Mantle endpoint — check the latest documentation for details.)

Team Governance: Cost Attribution and Bedrock Guardrails

Once your entire engineering team is using Claude Code, you'll quickly get asked: how much are we spending? Who's spending it?

Granular Cost Attribution

Without granular attribution, you'll just get a bill with a total — no way to tell whether a spending spike was one developer experimenting with Opus, or the entire team running Sonnet to meet a deadline. Bedrock automatically records which IAM principal (user or role) initiated each inference call, so you can filter by project, developer, or model.

By tagging IAM roles with metadata like team name and cost center, then activating cost allocation tracking, these tags appear as filterable columns in Cost Explorer. For the most granular data, use Cost and Usage Reports — each Bedrock inference request generates separate line items for input tokens, output tokens, cache reads, and cache writes.

You can go further by creating application inference profiles — named aliases for Bedrock models that enable structured cloud cost governance (FinOps) through the AWS cost allocation tag system. Traditional FinOps relies on manual tagging or after-the-fact analysis, while profiles encode attribution logic directly into infrastructure configuration: create a named profile for a model with cost allocation tags attached, and have each team use their respective profile ARN as the model ID. Attribution becomes structural rather than behavioral — regardless of how developers use the tool, tokens are automatically attributed to the corresponding tags. Combined with exporting AWS Cost and Usage Reports (CUR) to S3, you can use Athena or QuickSight to build real-time AI cost dashboards with multi-dimensional drill-down by model, team, and token type.

Configuring Bedrock Guardrails

Amazon Bedrock Guardrails is a content filtering layer that operates independently of the foundation model, acting on both the input and output sides of inference requests. Its core capabilities include: regex and NLP-based PII detection and redaction (supporting dozens of entity types including credit card numbers, social security numbers, and email addresses), topic rejection driven by semantic similarity (using embedding vectors to determine whether a request involves prohibited topics), and harmful content classification filtering. Because Guardrails runs independently of the model, it provides consistent policy enforcement across different model versions and vendors, making it a foundational component of enterprise unified AI governance frameworks. Teams commonly use it to prevent PII from leaking into generated code or to block inappropriate content from appearing in code suggestions, ensuring every team member gets a consistent and safe experience regardless of which project they're working on.

Configuration involves three steps: create a guardrail in Bedrock; publish a guardrail version; add the guardrail identifier and version as two headers in your settings file.

One common pitfall: if you're using a cross-region inference profile, you must also enable cross-region inference for the guardrail, otherwise requests routed to other regions won't have the guardrail policy applied — this is why many people wonder why their policies aren't taking effect. Guardrails have a separate billing model, so it's recommended to start with simple scenarios (typically just PII redaction and a small number of prohibited topics) and progressively tighten from there.

Summary: Benefits and Trade-offs

Running Claude Code on Amazon Bedrock gives you: data that stays in your own AWS account, higher throughput through cross-region inference, reduced cost and latency through prompt caching, granular cost attribution, content governance via Bedrock Guardrails, and the Mantle endpoint when native API compatibility is needed — all running on your existing AWS credentials.

Of course, any enterprise deployment path involves trade-offs. In exchange for compliance, IAM, and billing control, a handful of advanced features are still gradually making their way to Bedrock. Switching to the Mantle endpoint closes some of that gap, but not all of it. Fortunately, these capabilities are evolving quickly — it's worth checking the official documentation regularly for the latest developments.

To get started right away, simply add the two environment variables mentioned in this guide.