Deploy Claude apps gateway on AWS

This page walks through one way to run Claude apps gateway on AWS. The configuration is a working example for customer-managed infrastructure rather than a supported production deployment; use it to see how the pieces fit together before adapting it to your own environment. For the platform-agnostic requirements, see the deployment guide.

This example provisions Claude apps gateway on AWS with Amazon Bedrock as the model upstream, using either Amazon ECS on AWS Fargate or Amazon EKS for compute. Okta is the example identity provider (IdP), but any OpenID Connect (OIDC) compliant IdP works; see Identity provider setup for per-IdP details.

Bedrock isn’t the only Claude upstream on AWS. The gateway also supports Claude Platform on AWS, the Anthropic-operated Claude API with AWS authentication and AWS Marketplace billing, in place of Bedrock or alongside it. Its upstream entry, credentials, and IAM permissions differ from this page’s Bedrock-scoped ones; the Claude Platform on AWS upstream reference covers what changes, and the rest of this page applies unchanged.

Architecture

Diagram of Claude apps gateway on AWS: Claude Code clients connect over HTTPS to an internal Application Load Balancer fronting the gateway (ECS Fargate or EKS), which runs in private subnets alongside an Amazon RDS for PostgreSQL instance for session state. The gateway signs users in via OIDC against the corporate IdP, reads secrets from AWS Secrets Manager, forwards model requests to Amazon Bedrock using its IAM role, and pulls its image from Amazon ECR at deploy. — The example architecture, with Amazon Bedrock as the model upstream. A Claude Platform on AWS upstream occupies the same position.

The gateway runs as a private HTTPS endpoint on your network that developers sign in to through your IdP. Their Claude Code sessions reach Claude models on Amazon Bedrock through the gateway’s IAM role, so no model credentials land on developer machines. The reference configuration provisions:

Amazon ECS on AWS Fargate service or Amazon EKS Deployment running the gateway container
Amazon ECR repository for the gateway image
Amazon RDS for PostgreSQL instance in private subnets, not publicly accessible, for the gateway’s store
AWS Secrets Manager secrets for the JWT signing key, the OIDC client secret, and the Postgres URL
IAM role with bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, and bedrock:CountTokens, attached as the ECS task role or bound via IAM Roles for Service Accounts (IRSA) on EKS
Internal Application Load Balancer for HTTPS

Prerequisites

The walkthrough creates the gateway’s own resources, but it builds on network and identity infrastructure you already have. Before you start, you need:

An AWS account with permission to create the resources above
The AWS CLI v2 installed and authenticated, and Docker installed locally
A VPC with at least two private subnets in different Availability Zones, with outbound internet access through a NAT gateway; the internal load balancer needs subnets in two AZs, and the gateway needs egress to Bedrock and your IdP
An Okta OIDC web application with redirect URI https://<gateway-host>/oauth/callback; see Identity provider setup
A TLS hostname for the gateway, typically an internal DNS name in a Route 53 private hosted zone pointing at the load balancer, with an ACM certificate for that name, imported or issued by AWS Private CA

Set your environment variables

Every command on this page reads four values from your shell: AWS_REGION, ACCOUNT_ID, VPC_ID, and PRIVATE_SUBNETS. Pick a US region where Bedrock serves the Claude models you need. The walkthrough relies on the gateway’s built-in model catalog, which resolves to us.anthropic.* inference profiles, and the IAM policy grants those ARNs. In a non-US region, add a models: block with that geo’s inference-profile IDs and change the IAM policy’s ARN prefix to match. If you don’t have the VPC ID at hand, list your VPCs with aws ec2 describe-vpcs, then list that VPC’s subnets to find two private ones in different Availability Zones:

aws ec2 describe-subnets --filters "Name=vpc-id,Values=<your-vpc-id>" \
  --query 'Subnets[].{ID:SubnetId,AZ:AvailabilityZone,CIDR:CidrBlock}' --output table

Export all four before continuing:

export AWS_REGION=us-east-1   # a US region where Bedrock serves the Claude models you need
export ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"
export VPC_ID=<your-vpc-id>
export PRIVATE_SUBNETS="<subnet-id-a> <subnet-id-b>"

Deploy the gateway

The steps below provision the full deployment with aws commands.

Create the security groups

Three security groups chain the traffic path: your corporate network reaches the load balancer on 443, the load balancer reaches the gateway on 8080, and the gateway reaches Postgres on 5432. Nothing else is reachable. How you attach them depends on the compute track:

On ECS Fargate, the deploy step attaches $ALB_SG to the load balancer and $GW_SG to the service.
On EKS, the AWS Load Balancer Controller creates its own frontend security group for the ALB, so $ALB_SG and $GW_SG go unused: the deploy step’s inbound-cidrs annotation restricts the listener to your corporate network, and the database security group admits the cluster’s security group instead.

ALB_SG="$(aws ec2 create-security-group --group-name claude-gateway-alb \
  --description "Claude gateway ALB" --vpc-id "$VPC_ID" \
  --query GroupId --output text)"
GW_SG="$(aws ec2 create-security-group --group-name claude-gateway-svc \
  --description "Claude gateway service" --vpc-id "$VPC_ID" \
  --query GroupId --output text)"
DB_SG="$(aws ec2 create-security-group --group-name claude-gateway-db \
  --description "Claude gateway Postgres" --vpc-id "$VPC_ID" \
  --query GroupId --output text)"

aws ec2 authorize-security-group-ingress --group-id "$ALB_SG" \
  --protocol tcp --port 443 --cidr <your-corporate-cidr>
aws ec2 authorize-security-group-ingress --group-id "$GW_SG" \
  --protocol tcp --port 8080 --source-group "$ALB_SG"
aws ec2 authorize-security-group-ingress --group-id "$DB_SG" \
  --protocol tcp --port 5432 --source-group "$GW_SG"

Create the IAM roles and submit the use case form

The gateway runs with a dedicated task role whose only permission is invoking Claude models on Bedrock. Per the Bedrock upstream reference, the policy must cover both the cross-region inference-profile ARNs and the underlying foundation-model ARNs:

cat > bedrock-invoke.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream", "bedrock:CountTokens"],
    "Resource": [
      "arn:aws:bedrock:${AWS_REGION}:${ACCOUNT_ID}:inference-profile/us.anthropic.*",
      "arn:aws:bedrock:*::foundation-model/anthropic.*"
    ]
  }]
}
EOF
cat > ecs-trust.json <<'EOF'
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "ecs-tasks.amazonaws.com" },
    "Action": "sts:AssumeRole"
  }]
}
EOF

aws iam create-role --role-name claude-gateway-task \
  --assume-role-policy-document file://ecs-trust.json
aws iam put-role-policy --role-name claude-gateway-task \
  --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json

ECS also needs an execution role, which the ECS agent itself uses to pull the image from ECR and inject the Secrets Manager values created later. It is separate from the task role the gateway’s AWS SDK uses at runtime:

aws iam create-role --role-name claude-gateway-execution \
  --assume-role-policy-document file://ecs-trust.json
aws iam attach-role-policy --role-name claude-gateway-execution \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
cat > secrets-read.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],
    "Resource": [
      "arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-jwt-secret-??????",
      "arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-oidc-client-secret-??????",
      "arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-postgres-url-??????"
    ]
  }]
}
EOF
aws iam put-role-policy --role-name claude-gateway-execution \
  --policy-name read-gateway-secrets --policy-document file://secrets-read.json

The policy names one ARN per secret rather than a bare gateway-* wildcard, which in a shared account would also match unrelated secrets; the trailing -?????? matches exactly the random six-character suffix Secrets Manager appends to every secret’s ARN. A trailing -* would be a plain prefix glob and would also match longer names such as gateway-postgres-url-prod.The IAM policy grants the gateway permission to call Bedrock, and Bedrock enables model access by default in commercial regions. The remaining account-level gate is Anthropic’s one-time use case form: if no one in your account has submitted it, open the Amazon Bedrock console, select an Anthropic model from the Model catalog, and complete the form. Access is granted immediately after submission; see Claude Code on Amazon Bedrock for the AWS Organizations form and the IAM permissions the submitter needs.The EKS track reuses both policy documents on an IRSA role instead of the two ECS roles; see the deploy step.

Provision Amazon RDS for PostgreSQL

The instance runs in the private subnets with no public address and storage encryption on. The engine version is pinned to Postgres 16, which satisfies the gateway’s supported floor of PostgreSQL 14 and guarantees the parameter-group family below matches the instance.First, create the subnet group that places the database in the private subnets, and a parameter group with rds.force_ssl=1 so the server rejects plaintext connections. The engine version is pinned once because the parameter group’s family must match the engine major version the instance runs:

aws rds create-db-subnet-group --db-subnet-group-name claude-gateway-db \
  --db-subnet-group-description "Claude gateway" --subnet-ids $PRIVATE_SUBNETS

PG_VERSION=16
PG_FAMILY="postgres${PG_VERSION}"
aws rds create-db-parameter-group --db-parameter-group-name claude-gateway-db \
  --db-parameter-group-family "$PG_FAMILY" \
  --description "Claude gateway - require TLS on every connection"
aws rds modify-db-parameter-group --db-parameter-group-name claude-gateway-db \
  --parameters "ParameterName=rds.force_ssl,ParameterValue=1,ApplyMethod=immediate"

Then create the instance with a generated master password:

PGPASS="$(openssl rand -hex 24)"
aws rds create-db-instance --db-instance-identifier claude-gateway-db \
  --engine postgres --engine-version "$PG_VERSION" \
  --db-instance-class db.t4g.micro \
  --allocated-storage 20 --db-name claude_gateway \
  --master-username gateway --master-user-password "

Setup and access

Deployment

Gateways

Usage and costs

Plugin distribution

Security and data

Adoption

Deploy Claude apps gateway on AWS

Architecture

Prerequisites

Set your environment variables

Deploy the gateway

​Architecture

​Prerequisites

​Set your environment variables

​Deploy the gateway

Architecture

Prerequisites

Set your environment variables

Deploy the gateway