From bea5bb9eaa0ed55afb6104cf126d0d663918b03b Mon Sep 17 00:00:00 2001 From: Yevhenii Shcherbina Date: Thu, 16 Jul 2026 14:27:31 +0000 Subject: [PATCH 1/4] docs: document Bedrock mantle protocol --- docs/ai-coder/ai-gateway/providers.md | 37 ++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/docs/ai-coder/ai-gateway/providers.md b/docs/ai-coder/ai-gateway/providers.md index 4f9567342ec..4c5ce243db9 100644 --- a/docs/ai-coder/ai-gateway/providers.md +++ b/docs/ai-coder/ai-gateway/providers.md @@ -86,10 +86,16 @@ to have restricted permissions at the time of writing (June 2026). Bedrock providers serve Anthropic models hosted on AWS and authenticate with AWS credentials rather than a registered API key. Configure: -- A **region** (or a full base URL when routing through a proxy or a - non-standard endpoint that does not follow the - `https://bedrock-runtime..amazonaws.com` format). -- The **model** and **small fast model** identifiers. +- A **protocol**, either `InvokeModel` or `Mantle`. It determines the + endpoint format and which of the fields below apply. See + [Protocol: InvokeModel vs Mantle](#protocol-invokemodel-vs-mantle). +- An **endpoint** in the format the protocol requires: + `https://bedrock-runtime..amazonaws.com` for InvokeModel or + `https://bedrock-mantle..api.aws/anthropic` for Mantle. The AWS + region is read from the endpoint host. +- The **model** and **small fast model** identifiers, for InvokeModel + only. Mantle providers do not set them; the client chooses the model on + each request and AI Gateway forwards it upstream. Do not attach API keys to a Bedrock provider. @@ -111,6 +117,29 @@ AI Gateway resolves AWS credentials one of three ways: identities and supports cross-account Bedrock access. See [Assuming an IAM role](#assuming-an-iam-role). +#### Protocol: InvokeModel vs Mantle + +A Bedrock provider targets one of two AWS wire protocols: + +- **InvokeModel**: the legacy Bedrock runtime API. AI Gateway translates + each request into Bedrock's InvokeModel format and sends it to + `https://bedrock-runtime..amazonaws.com`. Still supported, but + Mantle is recommended for new deployments. +- **Mantle**: the newer Anthropic-compatible Bedrock endpoint, recommended + by AWS for new deployments. AI Gateway serves Anthropic models through + the native Messages API, forwarding the request body **unchanged** and + only applying AWS SigV4 signing with the provider's base identity. + +To route Claude Code through a Mantle provider, run it in mantle mode with +client-side signing disabled so the gateway signs centrally: + +```sh +export CLAUDE_CODE_USE_MANTLE=1 +export CLAUDE_CODE_SKIP_MANTLE_AUTH=1 +export ANTHROPIC_BEDROCK_MANTLE_BASE_URL="/api/v2/ai-gateway/" +export ANTHROPIC_AUTH_TOKEN="" +``` + #### Obtaining static Bedrock credentials When you cannot use the default credential chain, create a dedicated IAM From 33761a426b09b1ac7db9ee7bfd9f37321690f00f Mon Sep 17 00:00:00 2001 From: Yevhenii Shcherbina Date: Thu, 16 Jul 2026 16:07:14 +0000 Subject: [PATCH 2/4] docs: minor re-org --- docs/ai-coder/ai-gateway/providers.md | 42 ++++++++++++++------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/docs/ai-coder/ai-gateway/providers.md b/docs/ai-coder/ai-gateway/providers.md index 4c5ce243db9..86d65359098 100644 --- a/docs/ai-coder/ai-gateway/providers.md +++ b/docs/ai-coder/ai-gateway/providers.md @@ -97,26 +97,6 @@ with AWS credentials rather than a registered API key. Configure: only. Mantle providers do not set them; the client chooses the model on each request and AI Gateway forwards it upstream. -Do not attach API keys to a Bedrock provider. - -AI Gateway resolves AWS credentials one of three ways: - -- **AWS SDK default credential chain (recommended).** When no explicit - credentials are configured, the AWS SDK resolves them automatically - from the environment: IAM Roles (instance profiles, IRSA, ECS task - roles), shared config files, environment variables, SSO, and more. - Attaching an IAM Role to the compute running Coder follows - [AWS best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) - for temporary credentials. The role must permit `bedrock:InvokeModel` - and `bedrock:InvokeModelWithResponseStream` for the configured models. -- **Static credentials.** Provide an access key and secret for an IAM - user with the same Bedrock permissions. -- **Assumed IAM role.** Set a **Role ARN** to have the gateway assume - that role before calling Bedrock, signing requests with the resulting - temporary credentials. This works on top of either of the above base - identities and supports cross-account Bedrock access. See - [Assuming an IAM role](#assuming-an-iam-role). - #### Protocol: InvokeModel vs Mantle A Bedrock provider targets one of two AWS wire protocols: @@ -140,6 +120,28 @@ export ANTHROPIC_BEDROCK_MANTLE_BASE_URL="/api/v2/ai-gatewa export ANTHROPIC_AUTH_TOKEN="" ``` +#### AWS credentials + +Do not attach API keys to a Bedrock provider. + +AI Gateway resolves AWS credentials one of three ways: + +- **AWS SDK default credential chain (recommended).** When no explicit + credentials are configured, the AWS SDK resolves them automatically + from the environment: IAM Roles (instance profiles, IRSA, ECS task + roles), shared config files, environment variables, SSO, and more. + Attaching an IAM Role to the compute running Coder follows + [AWS best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) + for temporary credentials. The role must permit `bedrock:InvokeModel` + and `bedrock:InvokeModelWithResponseStream` for the configured models. +- **Static credentials.** Provide an access key and secret for an IAM + user with the same Bedrock permissions. +- **Assumed IAM role.** Set a **Role ARN** to have the gateway assume + that role before calling Bedrock, signing requests with the resulting + temporary credentials. This works on top of either of the above base + identities and supports cross-account Bedrock access. See + [Assuming an IAM role](#assuming-an-iam-role). + #### Obtaining static Bedrock credentials When you cannot use the default credential chain, create a dedicated IAM From df5481b82879c3abfafe3bbe298c2353fc9ab856 Mon Sep 17 00:00:00 2001 From: Yevhenii Shcherbina Date: Thu, 16 Jul 2026 16:16:11 +0000 Subject: [PATCH 3/4] chore: minor change --- .../AISettingsPage/ProvidersPage/components/ProviderForm.tsx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/site/src/pages/AISettingsPage/ProvidersPage/components/ProviderForm.tsx b/site/src/pages/AISettingsPage/ProvidersPage/components/ProviderForm.tsx index 27008a4958a..982237df9b1 100644 --- a/site/src/pages/AISettingsPage/ProvidersPage/components/ProviderForm.tsx +++ b/site/src/pages/AISettingsPage/ProvidersPage/components/ProviderForm.tsx @@ -573,9 +573,7 @@ export const ProviderForm: FC = ({ - - InvokeModel (default) - + InvokeModel Mantle From 5b145938c123eb942e3143a9dc5293a8bd12e369 Mon Sep 17 00:00:00 2001 From: Yevhenii Shcherbina Date: Thu, 16 Jul 2026 17:55:23 +0000 Subject: [PATCH 4/4] docs: split Bedrock protocols into separate sections --- docs/ai-coder/ai-gateway/providers.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/ai-coder/ai-gateway/providers.md b/docs/ai-coder/ai-gateway/providers.md index 86d65359098..01ace458246 100644 --- a/docs/ai-coder/ai-gateway/providers.md +++ b/docs/ai-coder/ai-gateway/providers.md @@ -88,7 +88,7 @@ with AWS credentials rather than a registered API key. Configure: - A **protocol**, either `InvokeModel` or `Mantle`. It determines the endpoint format and which of the fields below apply. See - [Protocol: InvokeModel vs Mantle](#protocol-invokemodel-vs-mantle). + [InvokeModel](#invokemodel) and [Mantle](#mantle). - An **endpoint** in the format the protocol requires: `https://bedrock-runtime..amazonaws.com` for InvokeModel or `https://bedrock-mantle..api.aws/anthropic` for Mantle. The AWS @@ -97,18 +97,19 @@ with AWS credentials rather than a registered API key. Configure: only. Mantle providers do not set them; the client chooses the model on each request and AI Gateway forwards it upstream. -#### Protocol: InvokeModel vs Mantle +#### InvokeModel -A Bedrock provider targets one of two AWS wire protocols: +The legacy Bedrock runtime API. AI Gateway translates each request into +Bedrock's InvokeModel format and sends it to +`https://bedrock-runtime..amazonaws.com`. Still supported, but +Mantle is recommended for new deployments. -- **InvokeModel**: the legacy Bedrock runtime API. AI Gateway translates - each request into Bedrock's InvokeModel format and sends it to - `https://bedrock-runtime..amazonaws.com`. Still supported, but - Mantle is recommended for new deployments. -- **Mantle**: the newer Anthropic-compatible Bedrock endpoint, recommended - by AWS for new deployments. AI Gateway serves Anthropic models through - the native Messages API, forwarding the request body **unchanged** and - only applying AWS SigV4 signing with the provider's base identity. +#### Mantle + +The newer Anthropic-compatible Bedrock endpoint, recommended by AWS for new +deployments. AI Gateway serves Anthropic models through the native Messages +API, forwarding the request body **unchanged** and only applying AWS SigV4 +signing with the provider's base identity. To route Claude Code through a Mantle provider, run it in mantle mode with client-side signing disabled so the gateway signs centrally: