Deploy on AWS ECS

AWS ECS on Fargate is the preferred AWS deployment. Keyring receives short-lived AWS credentials from the ECS task role and uses them only with the KMS keys listed in its configuration. us-east-1 is prefilled because most Composio infrastructure runs there. Keeping Keyring nearby can reduce request latency, but you can replace it with the AWS region that fits your requirements. Open Project Settings → General to find your Composio organization ID.

1. Create the KMS keys

Keyring uses three separate keys. Each key has one job, and Keyring rejects configurations that reuse a key for another purpose.

Key	Type	ECS task-role access
Credential root	Symmetric	`kms:Encrypt`, `kms:Decrypt`
Authorization gate	Symmetric	`kms:Encrypt`, `kms:Decrypt`
Secret transfer	RSA 3072	`kms:GetPublicKey`, `kms:Decrypt`

Each command labels its output and adds a KeyringPurpose tag. The output is easier to tell apart while you deploy, and the tag identifies each key when you return to AWS later.

Create the credential root key

This key wraps the project data keys that protect credentials for custom auth configs and sensitive fields returned during token exchange. Your key ARN will be different from the example. Copy the ARN value without the quotation marks and paste it into the Credential root key ARN field below.

Create the authorization-gate key

This independent key ensures protected credentials must pass through your Keyring before use, making the stored credential unusable without your authorization path. Copy the ARN value without the quotation marks and paste it into the Authorization-gate key ARN field below.

Create the secret-transfer key

This RSA key protects new credentials before they reach Composio. The Dashboard seals a credential with the public key, while the private key stays in your KMS. Copy the ARN value without the quotation marks and paste it into the Secret-transfer key ARN field below.

The generated IAM policy and encryption configuration now use the key ARNs you pasted. You do not need to replace them manually in later code blocks.

2. Create the ECS task role

The ECS task role gives Keyring access to only the three keys above. It is separate from the task execution role that ECS uses to pull the image, read task-definition secrets, and publish logs. Save this generated policy as keyring-kms-policy.json. It requires both exact key ARNs and the expected Keyring tags. Do not grant this role key administration or tag-management permissions. When IAM access depends on tags, changing a tag can also change access. Save this ECS trust policy as ecs-task-trust.json:

ecs-task-trust.json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "ecs-tasks.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}

Create the task role using the trust policy:

aws iam create-role \
  --role-name composio-keyring-task \
  --assume-role-policy-document file://ecs-task-trust.json

Attach the generated KMS policy to that role:

aws iam put-role-policy \
  --role-name composio-keyring-task \
  --policy-name composio-keyring-kms \
  --policy-document file://keyring-kms-policy.json

The KMS key policies must also enable IAM policies for your account or explicitly allow this task role. Keyring does not need kms:GenerateDataKey; it generates data keys locally and wraps them with kms:Encrypt.

3. Store the encryption configuration

Save this generated configuration as config.json. It references the three exact key ARNs and tells Keyring to obtain short-lived credentials from the ECS task role. Create a Secrets Manager secret containing that file: The standard image already contains the reviewed Composio origin policy. Do not add origin_policy unless Composio gives you a custom reviewed policy URL.

4. Register the Fargate task

The generated task definition includes your organization ID directly as AUTH_AUDIENCE. The task role uses its short name, so the file does not need your AWS account ID. Add your OpenTelemetry Collector sidecar to the complete task definition, then register it. The command asks AWS IAM for the execution-role ARN inline:

aws ecs register-task-definition \
  --execution-role-arn "$(aws iam get-role --role-name composio-keyring-execution --query Role.Arn --output text)" \
  --cli-input-json file://keyring-task-definition.json

Follow the telemetry delivery guide for the collector configuration. It should listen on 127.0.0.1:4318. Containers in one Fargate task share a network namespace, so Keyring can receive a local audit acknowledgment while the collector handles delivery to your observability backend. Mark the collector essential and start it before Keyring. Store any collector credential in Secrets Manager rather than the task definition.

5. Put the tasks behind an ALB

Run the Fargate tasks in private subnets without public IP addresses. Use an Application Load Balancer target group with target type ip and health path /healthz. After creating the ALB, target group, listener, and security groups, create the ECS service:

aws ecs create-service \
  --cluster <ECS_CLUSTER> \
  --service-name composio-keyring \
  --task-definition composio-keyring \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[<PRIVATE_SUBNET_1>,<PRIVATE_SUBNET_2>],securityGroups=[<TASK_SECURITY_GROUP>],assignPublicIp=DISABLED}" \
  --load-balancers "targetGroupArn=<TARGET_GROUP_ARN>,containerName=keyring,containerPort=7464"

Configure the two security groups:

Security group	Inbound rules	Outbound rules
ALB	TCP 443 from the four Composio `/32` addresses	TCP 7464 to the task security group
Task	TCP 7464 from the ALB security group only	HTTPS to Composio JWKS, KMS, providers, and OTLP

Add one explicit ALB rule for each Composio production egress address. Replace only the ALB security group placeholder:

These addresses are for Keyring requests from the Composio backend. They are not Composio trigger or webhook egress addresses. Confirm the current Keyring list with Composio before changing a production firewall.

Allow the ALB security group to reach port 7464 on the Keyring tasks. Do not expose the task security group directly to an IP range: Terminate TLS at the ALB with an ACM certificate.

6. Verify and connect

Check the public path after DNS and TLS are ready:

curl --fail https://keyring.example.com/healthz
curl --fail https://keyring.example.com/transfer-keys

Then connect the deployment to Composio. Confirm that Keyring initializes with the ECS task identity and can deliver audit events. Start with 1 vCPU and 2 GiB per task, then load test with your expected provider latency and payload mix. Keyring is stateless, so you can scale the ECS service horizontally. Keep ECS Exec disabled unless an approved incident workflow requires it. Never print task environment variables during diagnosis.

Get started

How Keyring works

Security

Deploy

Configure

Operate

Deploy on AWS ECS

1. Create the KMS keys

Create the credential root key

Create the authorization-gate key

Create the secret-transfer key

2. Create the ECS task role

3. Store the encryption configuration

4. Register the Fargate task

5. Put the tasks behind an ALB

6. Verify and connect

​1. Create the KMS keys

​Create the credential root key

​Create the authorization-gate key

​Create the secret-transfer key

​2. Create the ECS task role

​3. Store the encryption configuration

​4. Register the Fargate task

​5. Put the tasks behind an ALB

​6. Verify and connect

1. Create the KMS keys

Create the credential root key

Create the authorization-gate key

Create the secret-transfer key

2. Create the ECS task role

3. Store the encryption configuration

4. Register the Fargate task

5. Put the tasks behind an ALB

6. Verify and connect