# AWS Bedrock Hankweave can run models hosted on AWS Bedrock under your own AWS credentials and billing, for both codons (sealed agent tasks in a sequence) and sentinels (parallel observers). This page is the lookup reference for that support: how to spell Bedrock model ids, which harness each spelling lands on, where codons and sentinels get AWS credentials, what your AWS account needs, and how Bedrock failures are classified. Each section ends with pointers to the broader pages it depends on, so you can start anywhere and follow the links outward. ## When to run on Bedrock Bedrock is a fit when consolidated billing, private networking, or AWS compliance controls matter, because requests stay inside your AWS account and its guardrails. When those constraints do not apply, a direct provider API is simpler to set up and debug; see [authentication and models](/operate/authentication-and-models). Bedrock support is **\[since 0.9.0]**. ## Spelling Bedrock models Every place Hankweave accepts a model also accepts a Bedrock spelling: `amazon-bedrock/`. That covers a codon's `model`, a sentinel's `model`, and global overrides such as `HANKWEAVE_RUNTIME_MODEL`. The provider id `amazon-bedrock` comes from the models.dev registry, and the override is a free-form string validated at runtime by Hankweave's model registry (`LLMRegistry`). Anthropic-family ids use `anthropic.claude-…` for on-demand models and `.anthropic.claude-…` for cross-region inference profiles. The supported geography prefixes are `us.`, `eu.`, `jp.`, `au.`, `global.`, and `us-gov.`. The prefix matters in practice: AWS rejects a bare on-demand id for newer Anthropic models when on-demand throughput is unsupported, so use the serving geography or a `global.` profile where available. The catalog is embedded in the compiled binary at build time. The pinned release snapshot contains 119 Amazon Bedrock models out of 6,472 total and has no separate browsing surface, so re-check pinned ids against the `amazon-bedrock` provider's model list for each release; the CLI's `--validate` mode can then run its model self-tests. The two fragments below are valid one-line codon model settings in a hank (a run configuration). The first uses a cross-region inference profile for an Anthropic model; the second uses a non-Anthropic Bedrock model. Their enclosing `codon` shape is defined by `hank.schema.json`, the configuration schema. ```json {"model": "amazon-bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0"} ``` ```json {"model": "amazon-bedrock/deepseek.v3.2"} ``` See [model resolution](/reference/model-resolution) for the broader spelling and resolution rules. ## Which harness a Bedrock model lands on > **VersionNote:** Bedrock support landed in 0.9.0. In 0.10.0, harness selection became late-bound: when a plan resumes, the runtime uses the model's resolved identity rather than only its original spelling. `pi/amazon-bedrock/…` is the explicit override to the embedded Pi harness. The routing predicate sends a model to the Claude Agent SDK harness when its provider is `anthropic` or when it is an Anthropic-family id on `amazon-bedrock`. Non-Anthropic Bedrock models use the embedded Pi harness. The table summarizes the three spellings: | Model spelling | Harness | | ----------------------------------------- | ------------------------ | | `amazon-bedrock/` | Claude Agent SDK harness | | `pi/amazon-bedrock/` | embedded Pi harness | | `amazon-bedrock/` | embedded Pi harness | The `pi/` prefix is the explicit override. **\[changed 0.10.0]** Selection is late-bound at dispatch from the model's real identity. "Claude Code (Bedrock mode)" is an allowed alias for the Claude Agent SDK harness; the canonical name is Claude Agent SDK harness. For example, `pi/amazon-bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0` selects the embedded Pi harness even though the underlying model is Anthropic-family. On the Claude Agent SDK route, the runtime sets `CLAUDE_CODE_USE_BEDROCK=1` and passes an enumerated AWS environment-variable list to the Agent SDK subprocess. The list below is the complete set the subprocess receives; a non-Bedrock codon receives a byte-identical environment to the one it received before Bedrock support. ```ts const BEDROCK_AWS_ENV_VARS = [ "AWS_REGION", "AWS_DEFAULT_REGION", "AWS_BEARER_TOKEN_BEDROCK", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_PROFILE", "AWS_SHARED_CREDENTIALS_FILE", "AWS_CONFIG_FILE", "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI", "AWS_CONTAINER_CREDENTIALS_FULL_URI", // EKS Pod Identity (and any token-protected full-URI endpoint) needs the // authorization token alongside the URI, or the subprocess can't fetch creds. "AWS_CONTAINER_AUTHORIZATION_TOKEN", "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE", "AWS_WEB_IDENTITY_TOKEN_FILE", "AWS_ROLE_ARN", "AWS_ROLE_SESSION_NAME", "AWS_EC2_METADATA_DISABLED", // Custom/IPv6 IMDS endpoints: the child's SDK chain must target the same // metadata endpoint the preflight probe resolved. "AWS_EC2_METADATA_SERVICE_ENDPOINT", "AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE", "AWS_CA_BUNDLE", ] as const; ``` See [model resolution](/reference/model-resolution) and [runtime architecture](/contribute/runtime-architecture) for routing and harness boundaries. ## Where codons get AWS credentials Codons use the ambient AWS credential chain: sources visible to the Hankweave process, not credentials stored in a hank. On the Claude Agent SDK route, the quickest source is `AWS_BEARER_TOKEN_BEDROCK`. Other sources are `AWS_ACCESS_KEY_ID` plus `AWS_SECRET_ACCESS_KEY` and optional `AWS_SESSION_TOKEN`, `AWS_PROFILE` with single sign-on (SSO), ECS container credentials including EKS Pod Identity authorization tokens, IRSA web identity, and EC2 instance roles through the Instance Metadata Service (IMDS). A minimal bearer-token setup looks like this: ```bash export AWS_BEARER_TOKEN_BEDROCK="..." export AWS_REGION="us-east-1" ``` Before a run starts, Bedrock preflight checks these sources in order: gateway-managed authentication through `CLAUDE_CODE_SKIP_BEDROCK_AUTH`, ambient source detection, Claude settings helpers (`awsAuthRefresh` and `awsCredentialExport`), and then an IMDS probe. The probe requests an IMDSv2 token and requires a non-empty `iam/security-credentials/` listing within 500 ms. It honors `AWS_EC2_METADATA_SERVICE_ENDPOINT` and `AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE`, and is skipped when `AWS_EC2_METADATA_DISABLED=true`. Two interactions in that chain are easy to trip over. With `AWS_PROFILE` set, an environment key pair does not satisfy preflight because the AWS SDK skips its environment-key provider; the selected profile must provide usable credentials, and profile sections are inspected for actual credential keys, not merely for the section's presence. And EC2/IMDS instance roles authenticate only the Claude Agent SDK route: the embedded Pi route does not probe on-disk config files or IMDS, so Pi-routed Bedrock models need an explicit environment credential source. Region resolution follows the same ambient rule. `AWS_REGION` or `AWS_DEFAULT_REGION` wins. If neither is set and `AWS_PROFILE` or the default profile defines a region, the Agent SDK CLI resolves it from that profile while the runtime leaves the variable unset. Otherwise the runtime uses `us-east-1` and emits a startup warning naming the setting. > **Pitfall:** AWS settings are ambient-only. A codon's `env` block cannot set a key in the Bedrock AWS environment list or `CLAUDE_CODE_USE_BEDROCK`; Hankweave filters those entries with an "ambient-only" log line. Stripped `HANKWEAVE_AWS_*` aliases are ignored too, so a codon cannot switch AWS account or region through them. Short-term Bedrock API keys expire. An expired or invalid bearer token is a permanent failure, so the request is not retried; generate a long-term key in AWS Console → Bedrock → API keys. See [environment variables](/reference/environment-variables) for process variable names and scopes. ## Why sentinel credentials are narrower Sentinels do not share the codon credential chain. A Bedrock-modeled sentinel accepts explicit environment credentials only: `AWS_BEARER_TOKEN_BEDROCK`, or `AWS_ACCESS_KEY_ID` plus `AWS_SECRET_ACCESS_KEY` with optional `AWS_SESSION_TOKEN`. The sentinel-scoped `HANKWEAVE_SENTINEL_AWS_BEARER_TOKEN_BEDROCK` override is checked before the process-wide bearer token. Profile/SSO, container credentials, IRSA, and IMDS are not sentinel sources. The sentinel provider signs requests through its built-in `aws4fetch` path instead of the ambient chain; including the omitted credential-provider package would add a transitive tree of about 6 MB to the binary. The practical consequence: without an explicit source, the `amazon-bedrock` sentinel provider is marked `not-configured` with an error naming the accepted sources. Bedrock-modeled sentinels are skipped, while Bedrock codons on the same machine can run normally. The sentinel health check follows the configured region's geographic profile for the Anthropic Haiku model: `us-gov.` for GovCloud, `us.`, `eu.`, `jp.`, or `au.` where served, and `global.` otherwise. A geographic profile routes only within its own geography. A sentinel configuration selects its model with the same `amazon-bedrock/…` spelling used for codons: ```json { "model": "amazon-bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0" } ``` See [sentinel configuration](/reference/sentinel-config). ## Setting up the AWS account On the AWS side, three enablement rules apply. Serverless foundation models auto-enable on first invoke. Anthropic models require a one-time use-case form for first-time use. Marketplace-served models require one first invoke by a Marketplace-permissioned user; AWS has retired the console's "Model access" page. For permissions, the least-privilege action set is `bedrock:InvokeModel` plus `bedrock:InvokeModelWithResponseStream`. A cross-region `us.*` inference profile needs permission on both the profile ARN and its underlying foundation-model ARNs. The runtime's AccessDenied remedy recommends `Resource: "*"` for an invoke-only principal, so the restriction is expressed by the two allowed actions rather than by a resource ARN. Once the account is enabled and permissioned, the following AWS-side command verifies a Converse request for the selected model before you point Hankweave at it. ```text aws bedrock-runtime converse \ --region us-east-1 \ --model-id us.anthropic.claude-haiku-4-5-20251001-v1:0 \ --messages '[{"role":"user","content":[{"text":"Say OK"}]}]' ``` An invoke-only policy can use these actions: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream" ], "Resource": "*" } ] } ``` These are AWS-side procedures; verify the command and policy against the target account and region before relying on them. See [authentication and models](/operate/authentication-and-models) for the provider setup boundary. ## How Bedrock failures classify Bedrock authentication and access failures are permanent (`retriable: false`) and carry a remediation hint. They do not enter the retry path because the surfaced text has no HTTP status; the default would otherwise retry a failure that only the operator can fix. Ten Bedrock matchers run in declaration order, and the first matching row wins. The table below is the Bedrock slice of the classifier, rendered sorted by id for lookup; use `matchOrder`, not row order, to follow declaration precedence. `matchOrder` preserves each matcher's position in the complete classifier, so this slice starts at 3 rather than being renumbered. In the pattern column, `AND` and `OR` describe compound conditions, and `/…/` marks the regular expression used for the on-demand-throughput pattern. | id | pattern | classification | retriable | matchOrder | receipts | | ---------------------------- | -------------------------------------------------------------------------------------------- | -------------- | --------- | ---------- | ---------------------------------------------------------------- | | bedrock-access-denied | accessdeniedexception | api-error | false | 4 | error-classification.ts:178-184, error-classification.ts:350-358 | | bedrock-expired-token | expiredtokenexception | api-error | false | 7 | error-classification.ts:209-213, error-classification.ts:350-358 | | bedrock-invalid-credentials | unrecognizedclientexception OR security token included in the request is invalid | api-error | false | 5 | error-classification.ts:188-195, error-classification.ts:350-358 | | bedrock-model-not-found | resourcenotfoundexception OR the provided model identifier is invalid | api-error | false | 12 | error-classification.ts:257-263, error-classification.ts:350-358 | | bedrock-no-credentials | could not load credentials OR unable to locate credentials | api-error | false | 9 | error-classification.ts:226-233, error-classification.ts:350-358 | | bedrock-on-demand-throughput | /on-demand throughput isn.t supported/ | api-error | false | 11 | error-classification.ts:245-251, error-classification.ts:350-358 | | bedrock-pi-not-configured | provider is not configured: amazon-bedrock | api-error | false | 10 | error-classification.ts:237-243, error-classification.ts:350-358 | | bedrock-signature | invalidsignatureexception OR signaturedoesnotmatch OR signature we calculated does not match | api-error | false | 6 | error-classification.ts:199-207, error-classification.ts:350-358 | | bedrock-sso-session | sso session AND (not found OR invalid OR expired) | api-error | false | 8 | error-classification.ts:218-224, error-classification.ts:350-358 | | bedrock-sts-assume-role | sts:assumerole AND (accessdenied OR not authorized) | api-error | false | 3 | error-classification.ts:171-176, error-classification.ts:350-358 | Reading the rows in precedence order explains the remedies. The role-assumption matcher precedes generic `AccessDeniedException`, so a role denial gets the role remedy: check the role ARN, trust policy, and external-id or MFA requirements. Generic access denials point to IAM/SCP restrictions, cross-region permissions, first-time Anthropic access, or Marketplace first invoke. Invalid credentials point to the bearer token or key pair; expired short-term keys need a long-term key. Signature failures point to the access-key secret, expired or invalid SSO sessions to refreshed profile credentials, and missing credentials to an explicit bearer token, key pair, or profile plus region. The Pi-not-configured row requires an explicit environment source; the on-demand-throughput row requires a geography prefix or available `global.` profile. Signature matching runs before the timeout branch because AWS signature-error dumps contain `x-stainless-timeout` header lines; otherwise a broken credential chain could become retriable. One failure looks like a model problem but is a region problem: a wrong-region model appears as `ResourceNotFoundException` or Pi's "The provided model identifier is invalid." Both are permanent; set `AWS_REGION` to a serving region or use the `global.` inference profile id. The complete failure taxonomy and exit-code contract live in [errors and exit codes](/reference/errors-and-exit-codes); this page embeds only the Bedrock slice. ## When Bedrock features are unavailable Two route constraints limit which models and credential sources work: * A codon model must accept tool definitions in Converse requests. A model that rejects them cannot drive codons; DeepSeek-R1 surfaces "This model doesn't support tool use" as a permanent invalid request, while the shipped catalog carries `deepseek.v3.2` as the working alternative. * EC2 instance roles through IMDS authenticate only the Claude Agent SDK route. The embedded Pi route does not probe on-disk config files or IMDS; its `checkAuth` covers only Pi's credential store and ambient environment markers. Pi-routed Bedrock models, and all sentinels, need an explicit environment credential source. ## Where to continue from Bedrock * [Authentication and models](/operate/authentication-and-models) – provider credentials and model-selection planes. * [Model resolution](/reference/model-resolution) – model spellings, identity, and harness routing. * [Runtime architecture](/contribute/runtime-architecture) – harness feature sets and runtime boundaries. * [Sentinel configuration](/reference/sentinel-config) – sentinel model and credential settings. * [Environment variables](/reference/environment-variables) – process environment names and scopes. * [Errors and exit codes](/reference/errors-and-exit-codes) – the complete failure taxonomy and exit contract.