Skip to main content

​
AWS Bedrock Configuration

AWS Bedrock provides access to foundation models from Amazon and third-party providers like Anthropic Claude, Meta Llama, and Mistral.

​
Prerequisites

  1. An AWS account with Bedrock access enabled
  2. IAM credentials with permissions to invoke Bedrock models
  3. The desired models enabled in your AWS Bedrock console

​
Environment Variables

When running OpenHands with Docker, set the following environment variables using -e: 
docker run -it --pull=always \
    -e LLM_AWS_ACCESS_KEY_ID="your-access-key-id" \
    -e LLM_AWS_SECRET_ACCESS_KEY="your-secret-access-key" \
    -e LLM_AWS_REGION_NAME="us-east-1" \
    ...
Make sure you have enabled the Bedrock models you want to use in the AWS Console. Go to Amazon Bedrock → Model access and request access to the models you need.

​
UI Configuration

In the OpenHands UI Settings under the LLM tab:
  1. Enable Advanced options
  2. Set the following:
    • Custom Model to the Bedrock model ID (see Model IDs)
    • Leave Base URL empty (Bedrock uses AWS endpoints automatically)
    • Leave API Key empty (authentication is handled via AWS credentials)

​
Model IDs

Bedrock model IDs are managed by AWS and may change over time. Use the exact Model ID from the AWS Console or the AWS documentation (no bedrock/ prefix). Example format:
  • Custom Model: anthropic.claude-3-5-sonnet-20241022-v2:0
For a complete list of available models, see the AWS Bedrock documentation.

​
Cross-Region Inference

Some Bedrock models can be invoked across regions by prefixing the model ID with the target region (for example, us.):
  • Custom Model: <region>.<model-id>
No additional environment variable configuration is needed—keep using your normal Bedrock setup and credentials.

​
Using IAM Roles (Alternative to Access Keys)

If running OpenHands on AWS infrastructure (EC2, ECS, Lambda), you can use IAM roles instead of access keys:
  1. Attach an IAM role with Bedrock permissions to your compute resource
  2. Omit the LLM_AWS_ACCESS_KEY_ID and LLM_AWS_SECRET_ACCESS_KEY environment variables
  3. The AWS SDK will automatically use the instance role credentials

​
Troubleshooting

​
”No module named ‘boto3’” Error

If you encounter this error: 
litellm.APIConnectionError: No module named 'boto3'
ModuleNotFoundError: No module named 'boto3'
This means you’re using an older version of the OpenHands Docker image that doesn’t include the AWS SDK. Update to the latest version: 
docker pull docker.openhands.dev/openhands/openhands:latest
This issue is resolved in recent OpenHands releases. If you still see it, upgrade to latest (or a recent release tag).

​
Access Denied Errors

If you receive access denied errors:
  1. Verify your IAM credentials have the bedrock:InvokeModel permission
  2. Check that the model is enabled in your AWS Bedrock console
  3. Ensure you’re using the correct AWS region where the model is available

​
Model Not Found

If the model is not found:
  1. Verify the model ID is correct (check AWS documentation)
  2. Ensure the model is enabled in your Bedrock model access settings
  3. Check that the model is available in your selected AWS region